Authentifier tes calls à l'API

Deux méthodes : Bearer pour le web et le mobile (jeton de session), X-API-Key pour les scripts, les partenaires et Zapier. Choisis selon le contexte, jamais les deux à la fois.

Schemes disponibles

Authorization: BearerWeb, mobile

Le client récupère le jeton de la session en cours et l'envoie en Authorization: Bearer <jwt>. Le jeton est vérifié sans appel supplémentaire. Le workspace se choisit avec l'en-tête X-Workspace-Id. Sans lui, c'est le workspace actif du compte.

curl https://api.freelance-os.fr/v1/me \
  -H "Authorization: Bearer $JWT"

X-API-KeyPartners, scripts, Zapier

Génère une clé depuis Réglages > Clés API dans Freelance OS. Format fos_sk_live_<token>. La clé est liée à un seul workspace, pas besoin de X-Workspace-Id. Elle ne s'affiche qu'une fois : stocke-la tout de suite.

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.
•Gestion des clés : les routes /v1/api-keys exigent un jeton de session. Une clé ne peut ni créer ni révoquer une autre clé. C'est voulu.
•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 : seule l'empreinte de la clé est conservée, jamais la clé en clair. En cas de fuite, révoque-la puis génère-en une nouvelle.
•Mobile : connexion native, jeton rangé dans le trousseau sécurisé et renouvelé comme sur le web.

Erreurs courantes

Status

Cause

Fix

401

Header manquant ou mal formé

Vérifier Authorization: Bearer ... ou X-API-Key: fos_sk_live_...

401

Jeton de session expiré ou clé révoquée

Reconnecte-toi ou génère une nouvelle clé

403

User pas membre du workspace

Vérifier X-Workspace-Id ; rejoindre via une invitation

403

/v1/api-keys avec X-API-Key

Utilise un jeton de session à la place d'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

Réessaie avec le même Idempotency-Key ou patiente quelques secondes

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