Public API Authentication

The Public API uses OAuth client credentials for server-to-server access. This matches the Jortt-style pattern: use client_id and client_secret at the token endpoint, then call API resources with a Bearer token.

Public API resource calls do not accept x-api-key. The x-api-key header is not part of the new Public API auth model.

/public/v1/access/* uses a separate device-key contract for gates and scanners. It does not use OAuth scopes or fspt_... Bearer tokens. See the Access Devices section for x-device-key authentication.

1. Create an OAuth client

A coach creates a Public API OAuth client from the authenticated FITsociety app API:

POST /app/v1/integrations/public-api/clients
Authorization: Bearer <coach_token>
Content-Type: application/json

{
  "name": "Zapier sync",
  "scopes": ["clients:read", "clients:write", "bookings:read"],
  "defaultAssignedCoachId": "66f7b8b1e13c8d25f4d3d90a"
}

The response includes clientSecret once. Store it securely. FITsociety stores only a hash of the secret.

2. Request an access token

Exchange the client credentials for an access token:

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

Response:

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

If scope is omitted, FITsociety issues all scopes assigned to the client. Requested scopes must be a subset of the client’s assigned scopes.

Available scopes

Scope	Purpose
`platform:read`	Read the authenticated API client profile, capabilities, and scope catalog.
`audit_logs:read`	Read redacted Public API audit logs.
`company_catalog:read`	Read company profile, facilities, services, and policy metadata.
`locations:read`	Read company locations.
`locations:write`	Create, update, and archive company locations.
`clients:read`	Read Core CRM clients and client tags.
`clients:write`	Create, update, archive, and assign safe Core CRM client fields.
`client_onboarding:write`	Send portal invites and approve or reject pending client relationships.
`client_custom_fields:read`	Read company custom field definitions and client custom field values.
`client_custom_fields:write`	Update client custom field values.
`client_timeline:read`	Read sanitized client lifecycle timeline events.
`client_notes:read`	Read client notes.
`client_notes:write`	Create, update, and delete client notes.
`coaches:read`	Read coaches.
`coach_availability:read`	Read coach availability templates.
`coach_availability:write`	Replace coach availability templates.
`messages:read`	Read sanitized client chat threads and message DTOs.
`calendar_events:read`	Read calendar events.
`event_types:read`	Read event type labels used by event templates.
`event_types:write`	Create, update, and archive event type labels.
`event_templates:read`	Read event templates used by calendar availability and bookings.
`event_templates:write`	Create, update, and archive event templates.
`recurring_bookings:read`	Read recurring booking chains.
`recurring_bookings:write`	Update safe recurring booking settings and cancel chains.
`calendar_tasks:read`	Read blocking calendar tasks.
`calendar_tasks:write`	Create, update, and cancel blocking calendar tasks.
`booking_requests:read`	Read booking requests.
`booking_requests:write`	Approve or reject pending booking requests.
`location_availability:read`	Read location availability templates.
`location_availability:write`	Replace location availability templates.
`availability_rules:read`	Read availability closure metadata.
`availability_rules:write`	Replace availability closure metadata.
`availability:read`	Read bookable availability slots and short-lived booking tokens.
`bookings:read`	Read bookings and booking cancellation context.
`bookings:write`	Create bookings, update attendance, and cancel bookings.
`finance_invoices:read`	Read invoice metadata and line items.
`finance_invoice_pdfs:read`	Read existing invoice PDF download metadata.
`finance_payments:read`	Read payment/transaction metadata.
`finance_payment_requests:read`	Read payment request metadata.
`finance_payment_requests:write`	Create and cancel guarded payment requests.
`finance_chargebacks:read`	Read chargeback metadata.
`finance_payment_methods:read`	Read masked payment method and bank-account status.
`finance_invoice_messages:write`	Send invoice reminders and invoice copies for eligible invoices.
`finance_products:read`	Read product metadata.
`finance_products:write`	Assign/revoke supported products with finance guards.
`finance_subscriptions:read`	Read subscriptions.
`finance_subscription_actions:write`	Create subscription pause and cancellation requests for review.
`finance_memberships:write`	Assign membership products with finance guards.
`finance_credits:read`	Read credits and credit mutations.
`finance_credits:write`	Adjust client credits.
`measurements:read`	Read measurement types and entries.
`measurements:write`	Create, update, and soft-archive measurement entries.
`progress_summaries:read`	Read aggregated measurement progress summaries.
`progress_photos:read`	Read progress photo metadata and short-lived signed image URLs.
`habits:read`	Read client habits and habit entries.
`habits:write`	Create, update, and archive habit entries.
`goals:read`	Read public-safe client goal summaries.
`goals:write`	Update public-safe client goal fields.
`forms:read`	Read form metadata and sanitized form detail.
`form_assignments:write`	Assign intake forms.
`intakes:read`	Read current intake assignment status and submitted intake forms.
`checkups:read`	Read checkups and submitted checkup forms.
`checkups:write`	Assign and cancel checkup schedules.
`documents:read`	Read document and folder metadata.
`documents:write`	Link, update, and archive external document metadata.
`attendance_summaries:read`	Read aggregate booking attendance summaries.
`revenue_summaries:read`	Read aggregate invoice revenue summaries.
`retention_summaries:read`	Read aggregate client relationship summaries.
`webhooks:read`	List and read outbound webhook subscriptions.
`webhooks:write`	Create, update, delete, and test outbound webhook subscriptions.
`webhook_deliveries:read`	List and inspect outbound webhook delivery attempts.

3. Call a resource

Use the access token in the Authorization header:

Authorization: Bearer fspt_...

Example:

curl -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: create-client-jane-2026-07-14" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","email":"jane@example.com"}' \
  https://api.fitsociety.io/public/v1/clients

Write requests require a stable Idempotency-Key header. Reuse the same key only when retrying the exact same request.

Token lifetime

Credential	Prefix	Lifetime
Client ID	`fspc_`	Until revoked
Client secret	`fsps_`	Until rotated or revoked
Access token	`fspt_`	1 hour

Rotating a client secret revokes existing access tokens for that client.

Start here

Public API guides

Access Devices

1. Create an OAuth client

2. Request an access token

Available scopes

3. Call a resource

Token lifetime

​1. Create an OAuth client

​2. Request an access token

​Available scopes

​3. Call a resource

​Token lifetime

1. Create an OAuth client

2. Request an access token

Available scopes

3. Call a resource

Token lifetime