Quickstart

This guide takes you from nothing to a successful authenticated Public API call. You need a FITsociety coach account with a Manager or Admin role in the company you want to integrate with.

There is no sandbox environment. Every Public API call runs against real company data. Start with read-only scopes, and be deliberate with write scopes: creating a client or booking through the API creates it for real.

Create OAuth client credentials

A Manager or Admin coach creates Public API credentials from the coach dashboard:

Open Settings → Plugins in the FITsociety coach dashboard.
Open the Public API plugin.
On the OAuth clients tab, click Create OAuth client.
Give the client a recognizable name (for example CRM sync), pick the scopes it needs, and optionally set a default assigned coach for records created through the API.
Copy the client secret immediately. It is shown once; FITsociety stores only a hash.

You get a client ID prefixed fspc_ and a client secret prefixed fsps_.

The Public API plugin must be available for your company. If you do not see it under Settings → Plugins, ask FITsociety support to enable it.You can also create clients programmatically with POST /app/v1/integrations/public-api/clients. That endpoint requires an authenticated coach session token from the FITsociety app — coach tokens are not part of the Public API surface, so the dashboard is the practical path for most integrators.

Exchange credentials for an access token

Call the token endpoint with HTTP Basic auth (client_id as username, client_secret as password):

curl -X POST \
  -u "<client_id>:<client_secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=platform:read clients:read" \
  https://api.fitsociety.io/public/v1/oauth/token

Response:

{
  "access_token": "fspt_0123456789abcdef0123456789abcdef0123456789abcdef",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "platform:read clients:read"
}

Access tokens live for 1 hour. If you omit scope, the token gets all scopes assigned to the client; requested scopes must be a subset of the client’s assigned scopes.

Make your first call

GET /public/v1/me returns the profile of the authenticated API client — a safe read that confirms auth works end to end:

curl -H "Authorization: Bearer <access_token>" \
  https://api.fitsociety.io/public/v1/me

Expected response shape:

{
  "data": {
    "profile": {
      "clientId": "fspc_...",
      "publicApiClientId": "66a201f6962b241f55ebc216",
      "companyId": "5f2a01f6962b241f55ebc200",
      "name": "CRM sync",
      "status": "active",
      "scopes": ["platform:read", "clients:read"],
      "createdAt": "2026-08-23T09:00:00.000Z",
      "updatedAt": "2026-08-23T09:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 9,
      "resetSeconds": 1
    }
  }
}

If you get a 401, check that the token has not expired and that you are sending Authorization: Bearer fspt_... — the Public API does not accept x-api-key.

Pick a starter scope set

Start minimal and read-only, then add scopes as your integration grows:

Scope	Why start with it
`platform:read`	Read your own client profile, capabilities, and the scope catalog (`/me`, `/capabilities`, `/scopes`).
`clients:read`	List and read CRM clients — the anchor resource for most integrations.

Useful next additions: bookings:read, calendar_events:read, finance_invoices:read. Only add *:write scopes once the read path works, because writes hit live company data. The full catalog is on the Authentication page, or fetch it live from GET /public/v1/scopes.The starter scopes above need no consent. Scopes that expose health data or private communication are consent-gated and require the matching consents flag when the API client is created.

Where to go next

Contracts — response envelopes, pagination, idempotency, and rate limits. Read this before writing production code.
Errors — the error envelope and error keys you should handle.
The API Reference tab — endpoint-level request and response detail, generated from the OpenAPI contract.
The domain guides in the sidebar (clients, bookings, finance, progress, forms, reports, webhooks) — validation rules and privacy guardrails per domain.

Start here

Public API guides

Access Devices