> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first FITsociety Public API call in about 10 minutes.

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.

<Warning>
  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.
</Warning>

<Steps>
  <Step title="Create OAuth client credentials">
    A Manager or Admin coach creates Public API credentials from the coach
    dashboard:

    1. Open **Settings → Plugins** in the FITsociety coach dashboard.
    2. Open the **Public API** plugin.
    3. On the **OAuth clients** tab, click **Create OAuth client**.
    4. 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.
    5. 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_`.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Exchange credentials for an access token">
    Call the token endpoint with HTTP Basic auth
    (`client_id` as username, `client_secret` as password):

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    curl -H "Authorization: Bearer <access_token>" \
      https://api.fitsociety.io/public/v1/me
    ```

    Expected response shape:

    ```json theme={null}
    {
      "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`.
  </Step>

  <Step title="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](/public-api/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](/public-api/authentication#consent-gated-scopes) and require
    the matching `consents` flag when the API client is created.
  </Step>

  <Step title="Where to go next">
    * [Contracts](/public-api/contracts) — response envelopes, pagination,
      idempotency, and rate limits. Read this before writing production code.
    * [Errors](/public-api/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.
  </Step>
</Steps>