API & MCP/Authentication
Auth

Authenticate your API calls

Two schemes: Bearer for web and mobile (session token), X-API-Key for scripts, partners and Zapier. Pick one based on context, never both at once.

Available schemes

Authorization: BearerWeb, mobile

The client reads the token of the current session and sends it as Authorization: Bearer <jwt>. The token is verified without an extra round trip. The workspace is picked with the X-Workspace-Id header. Without it, the account's active workspace is used.

curl https://api.freelance-os.fr/v1/me \
  -H "Authorization: Bearer $JWT"
X-API-KeyPartners, scripts, Zapier

Generate a key from Settings > API keys in Freelance OS. Format fos_sk_live_<token>. The key is tied to a single workspace, no X-Workspace-Id needed. It is shown only once: store it right away.

curl https://api.freelance-os.fr/v1/me \
  -H "X-API-Key: fos_sk_live_..."

Scopes

Keys carry a list of scopes. For public API calls the scope check is currently minimal (read:* implied). We tighten route-level enforcement as the write surface grows.

Scope
Covers
read:*
All GET endpoints
write:*
POST / PATCH / DELETE on top of GET
*
Full access including admin surfaces
read:bookings (granular)
Reserved for future segmented keys

Limits & best practices

  • •Rate limit: 120 req/min sliding window per key or IP. 429 when exceeded, headers X-RateLimit-Limit / Remaining / Reset.
  • •Key management: the /v1/api-keys routes require a session token. A key can neither create nor revoke another key. That is on purpose.
  • •Expiration: optional. Bot keys can live forever; human / Zapier keys get a recommended 30/90/365-day window.
  • •Revocation: immediate on DELETE /v1/api-keys/<id>. No cache, no delay.
  • •Storage: only a fingerprint of the key is kept, never the key itself. If it leaks, revoke it then generate a new one.
  • •Mobile: native sign-in, token kept in the secure keychain and refreshed like on the web.

Common errors

Status
Cause
Fix
401
Missing or malformed header
Check Authorization: Bearer ... or X-API-Key: fos_sk_live_...
401
Session token expired or key revoked
Sign in again or generate a new key
403
User not a member of the workspace
Check X-Workspace-Id; join via an invite
403
/v1/api-keys with X-API-Key
Use a session token instead of a key
409
A call with the same Idempotency-Key is already in flight
Wait, then retry the same key to fetch the response
429
Rate limit exceeded
Exponential backoff, watch X-RateLimit-Reset
5xx
Transient error
Retry with the same Idempotency-Key or wait a few seconds
Try it live (Scalar) →Generate a key in Freelance OS