API Access for Developers
Authenticate against the Connected Performance REST API with JWT access and refresh tokens, keep a session alive, scope requests to an organization, and build a bespoke app on the full API surface.
Overview
This page is for developers. If you want an AI assistant to use your data, use the MCP server instead — see Connected Apps (MCP). Use the REST API when you're building your own software: an internal dashboard, a kiosk, a data pipeline, a white-labeled mobile app.
The REST API is the same API the Connected Performance web app calls. Authenticate as a user and you get that user's full capability, not a reduced subset.
Every request goes to the same host, whatever your organization or subdomain:
Two differences from the MCP server are worth knowing before you choose:
| REST API | MCP server | |
|---|---|---|
| Auth | JWT access + refresh tokens | OAuth, 90-day connection |
| Surface | Every endpoint the app uses | A curated tool set |
| Permission model | Your role | Your role, further narrowed by granted scopes |
| Built for | Your own code | AI assistants |
How To
Get an access token
POST /api/login with a JSON body:
Response:
The access token expires; the refresh token lives much longer and is what keeps your integration running unattended. Both lifetimes are server configuration and can change, so don't hardcode them. Refresh when a request returns 401, not on a timer.
Both are bearer credentials: anyone holding one can act as that user until it expires. Treat them like passwords.
Call the API
Send the access token as a bearer token on every request:
Requests and responses are JSON. Your role decides what you can reach: endpoints are gated by role and by organization, so a coach's token gets coach-level access and never sees another organization's data.
Refresh an expired access token
When the access token expires, requests fail with 401. Exchange the refresh token for a new access token via POST /api/refresh, passing the refresh token in the x-refresh header:
Response:
Refresh tokens are single-use. The token you just sent is consumed by that call and will not work again — overwrite your stored copy with the refreshToken from the response before the next refresh.
Presenting a refresh token that has already been exchanged is treated as a stolen credential, not a mistake: the session is ended and every token issued for it stops working, so the integration has to log in again. Two things cause this in practice — keeping the old token instead of the returned one, and firing two refreshes concurrently. If your client can refresh from more than one place at a time, serialize the refresh so only one call is in flight.
Wire it up in code
The usual shape: keep the access token in memory, refresh once on 401, retry the request, and only fall back to a full login if the refresh also fails.
Refresh on demand rather than on a timer. Token lifetimes are configuration, not contract, so don't hardcode them.
End a session
GET /api/logout/:id, authenticated, invalidates the user's session. Every access and refresh token issued for that session stops working. This is how you revoke a compromised integration credential: log the session out, then log in again to mint fresh tokens.
Scope requests to an organization
Normally you don't have to do anything: a token belongs to a user, a user belongs to an organization, and every request is scoped to that organization automatically.
Two cases need more:
-
Browser clients. Login from a browser is restricted to your organization's own domain. Calling
/api/loginfrom an unrelated web origin is rejected with "You can only log in from your organization's domain". -
Native and headless clients, which have no browser origin. A white-labeled build declares its organization with the
X-Org-Idheader, set to the organization's numeric id:Login then fails unless the user actually belongs to that organization, so a branded app can't be used to sign into a different facility.
Discover the endpoints
Non-production environments serve interactive OpenAPI docs at /api-docs. Production deliberately does not: the spec covers the whole API surface, so it isn't published publicly. Build against a non-production environment and ask support if you need the spec for one that isn't exposed.
Handle errors
| Status | Meaning | What to do |
|---|---|---|
400 | Bad request or missing refresh token | Fix the request body or headers |
401 | Missing, invalid or expired access token; invalidated session | Refresh once, then re-login |
403 | Authenticated but not permitted: wrong role, wrong organization, wrong login domain | Don't retry; use an account with the right role |
404 | Unknown route or record | Check the path |
429 | Rate limited | Back off for the retryAfter seconds in the response |
Retry 401 exactly once after a refresh. Retrying a 403 in a loop will never succeed.
Tips
- Create a dedicated integration user rather than reusing a person's login. It survives staff changes, and you can revoke it without locking anyone out.
- Give that user the lowest role that does the job. The API enforces roles, so a read-only integration on an admin account is one bug away from writing.
- Keep credentials in a secret manager, not in source and not in a client bundle. Anything shipped to a browser or a mobile binary is public.
- Do token exchange server-side. A public client that holds a refresh token holds a long-lived credential.
- Log the status code and response body on failure. Most integration bugs are a
403telling you exactly what's wrong.
Troubleshooting
Login returns 403 "You can only log in from your organization's domain". The request came from a browser origin that isn't your organization's domain. Call from a server, or from your own domain.
Login returns 403 "You can only log in to your organization's app".
The X-Org-Id header names an organization the user doesn't belong to. Drop the header or correct the id.
Everything returns 401 straight after a successful login.
The token isn't reaching the server. The header must be exactly Authorization: Bearer <token>, with the Bearer prefix.
Refresh returns 401 "Please login before refreshing your token". The session was invalidated, usually by a logout. Log in again.
Requests worked yesterday and now 401 constantly. The access token expired and nothing refreshed it. Add the refresh step.
429 responses under normal load. The limit is per client IP. Requests from many users behind one NAT share it. Back off and batch.
Related
- Connected Apps (MCP)
- User Roles & Permissions
- Import Third-Party Data
Referenced by
- 'REST API Endpoints'integrations
- 'Training Activities & Levels'facility
- 'VALD Integration'integrations
- 'Zapier & Webhooks'integrations