Connected Performance
Integrations

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:

https://management-api.connected-performance.com

Two differences from the MCP server are worth knowing before you choose:

REST APIMCP server
AuthJWT access + refresh tokensOAuth, 90-day connection
SurfaceEvery endpoint the app usesA curated tool set
Permission modelYour roleYour role, further narrowed by granted scopes
Built forYour own codeAI assistants

How To

Get an access token

POST /api/login with a JSON body:

curl -X POST https://management-api.connected-performance.com/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"integration@example.com","password":"…"}'

Response:

{
  "accessToken": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…",
  "role": "admin",
  "tosAccepted": true
}

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:

curl https://management-api.connected-performance.com/api/athletes \
  -H 'Authorization: Bearer eyJhbGciOi…'

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:

curl -X POST https://management-api.connected-performance.com/api/refresh \
  -H 'x-refresh: eyJhbGciOi…'

Response:

{ "accessToken": "eyJhbGciOi…", "refreshToken": "eyJhbGciOi…" }

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.

let accessToken = null;
 
async function call(path, options = {}) {
  const send = () =>
    fetch(`${API_HOST}${path}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        ...options.headers,
        Authorization: `Bearer ${accessToken}`,
      },
    });
 
  let response = await send();
 
  if (response.status === 401) {
    // refreshAccessToken must also persist the returned refreshToken — the one
    // it sent is now spent, and reusing it ends the session.
    accessToken = await refreshAccessToken(); // POST /api/refresh, x-refresh header
    response = await send();
  }
 
  return response;
}

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/login from 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-Id header, set to the organization's numeric id:

    curl -X POST https://management-api.connected-performance.com/api/login \
      -H 'Content-Type: application/json' \
      -H 'X-Org-Id: 42' \
      -d '{"email":"…","password":"…"}'

    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

StatusMeaningWhat to do
400Bad request or missing refresh tokenFix the request body or headers
401Missing, invalid or expired access token; invalidated sessionRefresh once, then re-login
403Authenticated but not permitted: wrong role, wrong organization, wrong login domainDon't retry; use an account with the right role
404Unknown route or recordCheck the path
429Rate limitedBack 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 403 telling 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.

  • Connected Apps (MCP)
  • User Roles & Permissions
  • Import Third-Party Data

Referenced by

On this page