Gérer les clés API

Les clés API authentifient chaque appel à l'API Coffrify. Cette page explique comment créer une clé avec les scopes dont vous avez besoin, comment lister les clés existantes d'un workspace, comment en ajuster les paramètres et comment la révoquer. La gestion des clés passe par les routes /v1/api-keys et requiert le scope api_keys:manage. Comme ce scope est sensible, son obtention est elle-même protégée par une étape de vérification supplémentaire, détaillée plus bas.

Créer une clé

Pour émettre une clé, envoyez un POST /v1/api-keys. Seul name est obligatoire. Vous choisissez l'environnement (live ou test), le type de clé (full ou restricted), la liste des scopes, et éventuellement une date d'expiration et une liste d'adresses IP autorisées.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const created = await coffrify.apiKeys.create({
  name: 'Intégration facturation',
  environment: 'live',
  key_type: 'restricted',
  scopes: ['transfers:read', 'transfers:write', 'webhooks:read'],
  expires_in_days: 90,
  allowed_ips: ['203.0.113.4'],
});
 
// La valeur complète n'est lisible qu'ici.
console.log(created.key);
console.log(created.key_prefix);

La réponse renvoie l'objet clé créé, complété de deux champs particuliers : key, la valeur complète à enregistrer, et warning, un rappel que cette valeur ne sera plus jamais affichée. Le champ key_prefix (par exemple cof_live_3f9a2c1b...) est, lui, conservé côté Coffrify : c'est l'identifiant abrégé qui vous permet de reconnaître la clé dans les listes et les journaux.

{
  "id": "key_8a1f...",
  "name": "Intégration facturation",
  "key_prefix": "cof_rk_live_3f9a2c1b...",
  "key_type": "restricted",
  "scopes": ["transfers:read", "transfers:write", "webhooks:read"],
  "environment": "live",
  "allowed_ips": ["203.0.113.4"],
  "expires_at": "2026-09-08T10:00:00Z",
  "created_at": "2026-06-10T10:00:00Z",
  "key": "cof_rk_live_3f9a2c1b...",
  "warning": "Save this key now - it will not be shown again."
}

Clés complètes ou restreintes

Une clé full (préfixes cof_live_ / cof_test_) accorde implicitement tous les scopes : pratique pour le développement, mais à réserver à des contextes de confiance. Une clé restricted (préfixes cof_rk_live_ / cof_rk_test_) n'accorde que les scopes que vous listez, ce qui suit le principe du moindre privilège. Privilégiez une clé restreinte par intégration.

Étape de vérification pour les scopes sensibles

Certains scopes confèrent un contrôle élevé sur le workspace : members:manage, sessions:manage, audit:export, gdpr:export, domains:manage, workspace:manage, workspace:billing et api_keys:manage. Émettre une clé qui les accorde déclenche une étape de vérification supplémentaire (MFA). Une clé full accordant tout, elle déclenche toujours cette étape. Vous fournissez alors un code de vérification dans le champ mfa_code.

Si le code manque ou est invalide, l'API répond 401 avec le code d'erreur mfa_required, et la réponse précise les scopes sensibles concernés. Renvoyez la même requête en ajoutant un mfa_code valide.

curl -X POST https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer $COFFRIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Outil conformité",
    "environment": "live",
    "key_type": "full",
    "scopes": ["audit:export", "gdpr:export"],
    "mfa_code": "123456"
  }'

Lister les clés

Un GET /v1/api-keys renvoie les clés du workspace, de la plus récente à la plus ancienne. La réponse a la forme { "object": "list", "data": [...] }. Chaque entrée expose ses métadonnées (nom, key_prefix, type, scopes, environnement, état actif, expiration, dernière utilisation), mais jamais la valeur complète de la clé.

const keys = await coffrify.apiKeys.list();
for (const k of keys.data) {
  console.log(k.key_prefix, k.key_type, k.is_active);
}

Modifier une clé

Un PATCH /v1/api-keys/{id} met à jour les champs modifiables d'une clé : name, description, is_active (pour désactiver ou réactiver sans révoquer), allowed_ips et scopes. La liste de scopes doit rester non vide, et les restrictions des clés restreintes s'appliquent ici aussi. La valeur de la clé reste inchangée : modifier ses paramètres ne la régénère pas.

curl -X PATCH https://api.coffrify.com/v1/api-keys/key_8a1f... \
  -H "Authorization: Bearer $COFFRIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false, "allowed_ips": ["203.0.113.4", "203.0.113.5"] }'

Révoquer une clé

Un DELETE /v1/api-keys/{id} révoque la clé : elle cesse immédiatement d'authentifier les appels. Vous pouvez préciser une reason (par exemple manual, compromised, rotated, suspicious_activity). La réponse confirme la révocation.

curl -X DELETE https://api.coffrify.com/v1/api-keys/key_8a1f... \
  -H "Authorization: Bearer $COFFRIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "compromised" }'

Bonnes pratiques

• Une clé restreinte par intégration, avec uniquement les scopes nécessaires.
• Réservez les clés test (cof_test_ / cof_rk_test_) aux environnements hors production.
• Définissez expires_in_days et allowed_ips dès que le contexte le permet.
• Ne committez jamais une clé : passez par des variables d'environnement ou un coffre à secrets.
• Révoquez ou faites tourner immédiatement toute clé que vous soupçonnez compromise.