Authentification
Comment fonctionnent les clés API, où les placer, et ce qu'il ne faut PAS en faire.
L'API boxioo authentifie chaque requête avec un header unique portant une clé API. Pas de session, pas de cookie, pas de danse OAuth — juste une longue chaîne opaque que vous gardez secrète.
Le header
Le préfixe ApiKey (avec cette casse exacte) est obligatoire.
Pour compatibilité, l'API accepte aussi :
La forme Authorization: ApiKey … est recommandée.
Anatomie d'une clé
Chaque clé ressemble à l'un de ces formats :
| Format | Usage |
|---|---|
bk_live_... | Données de production. Vrais enregistrements. |
Le préfixe de 14 caractères ( bk_live_a1b2c3d4 ) est sûr à logger et afficher
dans vos dashboards — le reste de la clé est la partie secrète.
Cycle de vie
- Création dans le dashboard → la clé en clair est affichée une fois
- Utilisation en l'envoyant dans le header
Authorization - Rotation en créant une nouvelle clé, en la déployant dans votre code, puis en révoquant l'ancienne
- Révocation à tout moment — instantanée, sans délai de grâce. Toute
requête en cours utilisant une clé révoquée renvoie
401 api_key_revoked.
Scopes
Chaque clé porte un ensemble de scopes qui restreignent ce
qu'elle peut faire. Une clé avec seulement records:read ne peut pas créer
d'enregistrement — le serveur renvoie 403 insufficient_scope. Choisissez le
plus petit ensemble de scopes qui suffit à la tâche.
Le scope joker * donne un accès total. À utiliser avec parcimonie — il
apparaît dans les journaux d'audit dans une couleur distincte pour qu'un
relecteur le remarque.
Expiration
Les clés peuvent avoir une date expiresAt optionnelle. Passé cette date, les
appels renvoient 401 api_key_expired. Nous envoyons un email de rappel 7
jours avant l'expiration à l'utilisateur qui a créé la clé.
Bonnes pratiques
Stockez dans un gestionnaire de secrets
Utilisez HashiCorp Vault, AWS Secrets Manager, 1Password, Doppler, ou équivalent. Ne committez jamais une clé dans git, même un repo privé.
Une clé par intégration
Ne partagez pas une seule clé entre Zapier, votre job BI et un partenaire. Des clés séparées = pistes d'audit séparées et révocation isolée.
Rotation trimestrielle
Même sans incident. Préparez un runbook de rotation pour que ça prenne 10 minutes, pas une urgence.
Scope adapté à la tâche
Un job de synchro en lecture seule a besoin de records:read, pas de *.
Ne jamais utiliser une clé API dans un navigateur
Les clés API sont des identifiants serveur. Si vous livrez du JavaScript qui en contient une et s'exécute dans le navigateur d'un client, c'est déjà perdu — n'importe quel visiteur peut extraire la clé depuis les DevTools.
Pour les applis navigateur, construisez un backend léger qui détient la clé et
relaie les requêtes. Le CORS est d'ailleurs désactivé sur /v1/* pour cette
raison : même si une clé fuitait dans un navigateur, des sites tiers
malveillants ne pourraient pas l'utiliser.
Que se passe-t-il en cas d'échec d'authentification
| Statut | code | Cause |
|---|---|---|
401 | invalid_api_key | Header manquant ou clé inconnue |
401 | api_key_revoked | Clé révoquée depuis le dashboard |
401 | api_key_expired | Clé ayant dépassé son expiresAt |
403 | tenant_mismatch | X-Tenant-Id différent du tenant de la clé |
403 | insufficient_scope | La clé n'inclut pas le scope requis |
Voir Erreurs pour l'enveloppe complète.