Authentifier tes calls a l'API
Deux schemes : Bearer pour le web/mobile (session Supabase),
X-API-Key pour les scripts/partners/Zapier. Choisis selon le
contexte, jamais les deux en meme temps.
Schemes disponibles
Le client recupere le JWT depuis la session Supabase
(supabase.auth.getSession()) et l'envoie en
Authorization: Bearer <jwt>. Validation offline
HS256, pas de round-trip Supabase. Le workspace est resolu via
X-Workspace-Id ou app_metadata.active_workspace_id.
curl https://api.freelance-os.fr/v1/me \ -H "Authorization: Bearer $JWT"
Genere une cle depuis /settings/api-keys dans Kernel.
Format fos_sk_live_<token>, scopee a un seul
workspace (pas besoin de X-Workspace-Id). Le plaintext
s'affiche une seule fois, stocke-le immediatement.
curl https://api.freelance-os.fr/v1/me \ -H "X-API-Key: fos_sk_live_..."
Scopes
Les cles portent une liste de scopes. Pour les calls API publics, le check de scope est pour l'instant minimal (read:* implicite). On verrouille route-level a mesure que la surface ecrit grandit.
| Scope | Couvre |
|---|---|
read:* | Tous les endpoints GET |
write:* | POST / PATCH / DELETE en plus des GET |
* | Acces total incluant les surfaces admin |
read:bookings (granular) | Reserve aux futures cles segmentees |
Limites & bonnes pratiques
- Rate limit : 120 req/min sliding window par cle ou IP. 429 au depassement, headers
X-RateLimit-Limit / Remaining / Reset. - Management gate : les endpoints
/v1/api-keysexigent un JWT. Une cle ne peut pas en creer ou en revoquer une autre, par design. - Expiration : optionnelle. Les cles bot peuvent vivre sans expiration ; les cles humaines / Zapier ont une fenetre 30/90/365 jours conseillee.
- Revocation : immediate des le
DELETE /v1/api-keys/<id>. Pas de cache, pas de delai. - Stockage :
token_hash = sha256(plaintext)en DB, plaintext jamais persiste. En cas de fuite, revoke + regenere. - Mobile : login Supabase natif, stocke le JWT dans le keychain securise, refresh comme web.
Erreurs courantes
| Status | Cause | Fix |
|---|---|---|
| 401 | Header manquant ou mal forme | Verifier Authorization: Bearer ... ou X-API-Key: fos_sk_live_... |
| 401 | JWT expire ou cle revoquee | Re-auth (Supabase) ou regen une cle |
| 403 | User pas membre du workspace | Verifier X-Workspace-Id ; rejoindre via une invitation |
| 403 | /v1/api-keys avec X-API-Key | Utiliser un JWT user, pas une cle |
| 429 | Rate limit depasse | Backoff exponentiel, regarder X-RateLimit-Reset |
| 5xx | Erreur transitoire | Retry avec idempotency-key (TODO) ou backoff |