Partner API reference

The Partner API (/api/v2/external/*) is the OAuth-protected surface for third-party developer applications. It is separate from the internal /v1 surface used by the Forzelite web and mobile apps.

Availability: the Partner API is launch-gated (requirement DEV-001). It is enabled in development environments and remains disabled in production until security and release review completes — gated calls return 503 feature_unavailable.

POST /api/v2/external/oauth/token

OAuth 2.0 client_credentials grant (RFC 6749 §4.4). Form-encoded body: grant_type, client_id, client_secret, optional space-delimited scope. Returns a signed bearer token carrying client_id, tenant_id, granted scopes, and expiry. Only scopes granted to the client at registration can be requested.

curl -X POST "$API/api/v2/external/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d "scope=athletes:read usage:read"

GET /api/v2/external/whoami

Token introspection helper — returns the calling client's identity, tenant, scopes, and token expiry. Useful for smoke tests.

GET /api/v2/external/athletes/{athlete_id}

Read an athlete profile. Requires the athletes:read scope. Consent-gated: the athlete must have public visibility enabled; otherwise the API returns 404 (never 403) to prevent enumeration of athlete ids.

POST /api/v2/external/insights

Insert a partner-generated insight card for an athlete in your tenant. Requires the insights:write scope. Cards are tagged with your client_id so coaches can clearly see partner-sourced content.

GET /api/v2/external/usage

Return your client's own recent api_usage_log rows (method, path, status, duration, timestamp). Requires the usage:read scope. The Usage page of this portal renders this data live.

Scopes

athletes:read — read consent-gated athlete profiles
athletes:read-metrics — reserved for metric reads
insights:write — submit partner insight cards
usage:read — introspect your own usage log

Client management

OAuth clients are registered per tenant by a tenant admin — either on this portal's Clients page or directly against the tenant-admin endpoints POST/GET/DELETE /api/v2/external/clients. The client secret is returned exactly once at creation; only its hash is persisted. Revocation is a soft delete and takes effect immediately.