Authentifier tes calls à 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 même temps.
Schemes disponibles
Le client récupère 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 résolu via
X-Workspace-Id ou app_metadata.active_workspace_id.
curl https://api.freelance-os.fr/v1/me \ -H "Authorization: Bearer $JWT"
Génère une clé depuis /settings/api-keys dans Kernel.
Format fos_sk_live_<token>, scopée à un seul
workspace (pas besoin de X-Workspace-Id). Le plaintext
s'affiche une seule fois, stocke-le immédiatement.
curl https://api.freelance-os.fr/v1/me \ -H "X-API-Key: fos_sk_live_..."
Scopes
Les clés 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 à mesure que la surface écrit grandit.
| Scope | Couvre |
|---|---|
read:* | Tous les endpoints GET |
write:* | POST / PATCH / DELETE en plus des GET |
* | Accès total incluant les surfaces admin |
read:bookings (granular) | Réservé aux futures clés segmentées |
Limites & bonnes pratiques
- Rate limit : 120 req/min sliding window par clé ou IP. 429 au dépassement, headers
X-RateLimit-Limit / Remaining / Reset. - Management gate : les endpoints
/v1/api-keysexigent un JWT. Une clé ne peut pas en créer ou en révoquer une autre, par design. - Expiration : optionnelle. Les clés bot peuvent vivre sans expiration ; les clés humaines / Zapier ont une fenêtre 30/90/365 jours conseillée.
- Revocation : immédiate dès le
DELETE /v1/api-keys/<id>. Pas de cache, pas de délai. - Stockage :
token_hash = sha256(plaintext)en DB, plaintext jamais persisté. En cas de fuite, revoke + régénère. - Mobile : login Supabase natif, stocke le JWT dans le keychain sécurisé, refresh comme web.
Erreurs courantes
| Status | Cause | Fix |
|---|---|---|
| 401 | Header manquant ou mal formé | Vérifier Authorization: Bearer ... ou X-API-Key: fos_sk_live_... |
| 401 | JWT expiré ou clé révoquée | Re-auth (Supabase) ou regen une clé |
| 403 | User pas membre du workspace | Vérifier X-Workspace-Id ; rejoindre via une invitation |
| 403 | /v1/api-keys avec X-API-Key | Utiliser un JWT user, pas une clé |
| 409 | Un appel avec le même Idempotency-Key est déjà en cours | Attendre puis retry la même clé pour récupérer la réponse |
| 429 | Rate limit dépassé | Backoff exponentiel, regarder X-RateLimit-Reset |
| 5xx | Erreur transitoire | Retry avec Idempotency-Key (dedup) ou backoff |