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

Authorization: BearerWeb, mobile

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"

X-API-KeyPartners, scripts, Zapier

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-keys exigent 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

Tester en live (Scalar) →Générer une clé dans Kernel