Authorization: Bearer <token>, sauf l’engine interne qui utilise un header dédié. Aucune route publique n’accepte d’auth basique ni de token en query string (sauf le widget chat embarqué, qui passe sa clé en ?api_key= pour des raisons de CORS).
Vue d’ensemble
Bearer JWT (Supabase)
Le dashboard s’authentifie via le SDK Supabase. Tu n’as rien à coder côté front :supabase.auth.getSession() te retourne le token, et le client REST l’envoie automatiquement.
supabase.auth.getUser(token). Le user.id est ensuite résolu en client_id via la table client_users (membres) ou clients.owner_user_id (propriétaire).
API key
Pour toute intégration serveur à serveur, génère une clé API dédiée.Créer une clé
- Connecte-toi au dashboard.
- Va dans API & Intégrations → Clés API → Nouvelle clé.
- Donne-lui un label descriptif (ex.
prod-shopify-bridge,n8n-staging). - Copie la clé immédiatement — elle ne sera plus affichée en clair après.
ak_ suivi de 32 caractères hexadécimaux (16 octets de crypto.getRandomValues). Exemple : ak_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6. Stockage en base : table client_api_keys, colonnes (client_id, key_value, label, is_active).
Utiliser une clé
Révoquer une clé
Dashboard → API & Intégrations → Clés API → Supprimer. La clé est marquéeis_active = false ; toute requête entrante est rejetée en 401 immédiatement (pas de cache).
Si tu suspectes une fuite, révoque d’abord, génère ensuite. La révocation prend effet en moins d’une seconde, donc l’attaquant perd l’accès avant que tu ne déploies la nouvelle clé.
API key MCP (mcp_…)
Les clés mcp_ sont créées automatiquement par le flow OAuth quand tu connectes Claude Desktop ou Cursor à Actero (endpoint POST /api/mcp/token, grant authorization_code avec PKCE S256). Elles ont les mêmes droits qu’une clé ak_ mais portent un label Claude Desktop (MCP) pour qu’on puisse les distinguer.
Tu n’as pas à les générer manuellement. Le refresh token retourné par le flow OAuth est la clé elle-même : un grant refresh_token retourne le même access_token (les clés Actero n’expirent pas tant qu’elles sont actives).
Erreurs d’authentification
Bonnes pratiques
- Une clé par environnement (prod, staging, CI). Tu peux les révoquer indépendamment.
- Stocke en variable d’environnement, jamais en dur. Préfixe
ACTERO_API_KEYpour cohérence. - Ne logge jamais la clé en clair. Si tu logges la requête sortante, masque la valeur après les 8 premiers caractères.
- Rotate trimestriellement si tu manipules des données sensibles. Génère la nouvelle, déploie, puis révoque l’ancienne.
- Ne réutilise pas une clé entre plusieurs clients/tenants : chaque clé est scopée à un seul
client_id.