Authentification : clés API et scopes

Chaque requête adressée à api.coffrify.com/v1 doit être authentifiée via un en-tête Authorization: Bearer <clé>. L'API valide la clé à chaque appel : elle vérifie son hash SHA-256, son cycle de vie (révoquée, expirée, quota max d'usages atteint), la liste d'IP autorisées si elle est définie, puis contrôle que la clé porte le scope requis par l'endpoint. Aucune session, aucun cookie, aucun OAuth n'est nécessaire pour les intégrations serveur-à-serveur.

Endpoints de gestion des clés

Authentification requise

Ces deux endpoints requièrent le scope api_keys:manage. Ce scope est classé risque élevé dans le catalogue Coffrify : il déclenche un step-up d'authentification lors de la création (voir section "Création d'une clé" ci-dessous). Seules les clés de type full (cof_live_*, cof_test_*) peuvent porter ce scope. Les clés restreintes (cof_rk_live_*, cof_rk_test_*) ne peuvent jamais l'obtenir.

Formats de clés acceptés

L'API reconnaît six familles de préfixes. Utilisez toujours le bon type pour votre contexte :

Catalogue des 43 scopes

Chaque scope correspond à une permission fine. L'API applique une hiérarchie : un scope large (workspace:manage) satisfait automatiquement les scopes plus fins qu'il couvre (members:read, analytics:read, audit:read, billing:read, etc.). Le wildcard * accorde toutes les permissions (uniquement disponible en session dashboard).

Corps de la requête (POST /v1/api-keys)

Exemples d'appels

# Créer une clé restreinte pour lire et créer des transferts
curl -X POST https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer cof_live_<votre_cle>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline - transferts",
    "description": "Clé utilisée par le pipeline GitHub Actions",
    "environment": "live",
    "key_type": "restricted",
    "scopes": ["transfers:read", "transfers:write"],
    "expires_in_days": 90
  }'

Réponse (201 Created)

La valeur brute de la clé (key) n'est retournée qu'une seule fois dans cette réponse. Elle n'est jamais stockée en clair : seul son hash SHA-256 est conservé en base. Sauvegardez-la immédiatement dans votre gestionnaire de secrets.

{
  "id": "ak_01hwxyz",
  "name": "CI pipeline - transferts",
  "description": "Clé utilisée par le pipeline GitHub Actions",
  "key_prefix": "cof_rk_live_a3f9c12b...",
  "key_type": "restricted",
  "scopes": ["transfers:read", "transfers:write"],
  "environment": "live",
  "allowed_ips": null,
  "expires_at": "2026-09-04T00:00:00.000Z",
  "max_uses": null,
  "created_at": "2026-06-06T14:23:11.000Z",
  "key": "cof_rk_live_a3f9c12b7e4d8f3a...",
  "warning": "Save this key now - it will not be shown again."
}

La réponse GET /v1/api-keys retourne la même structure pour chaque clé mais sans le champ key, remplacé par le préfixe visible (key_prefix). Elle inclut également les champs is_active, used_count, last_used_at et revoked_at.

En-têtes de réponse

Chaque réponse inclut systématiquement ces en-têtes, quel que soit le résultat :

Step-up MFA pour les scopes à risque élevé

Créer une clé full ou incluant un scope à risque élevé (ex : api_keys:manage, workspace:manage, members:manage, audit:export, gdpr:export, sessions:manage, domains:manage, workspace:billing) déclenche un step-up obligatoire. Deux cas selon la configuration MFA du compte :

• MFA activé (TOTP) : fournir mfa_code avec le code à 6 chiffres de l'application d'authentification. Un code de récupération (8+ caractères) est aussi accepté.
• MFA non activé : fournir confirm_sensitive: true dans le corps. L'API logge l'action et retourne un avertissement. Il est fortement conseillé d'activer le MFA (Paramètres du compte) pour passer au flux TOTP.

# Exemple avec step-up TOTP pour une clé full (scopes admin)
curl -X POST https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer cof_live_<votre_cle>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin automation",
    "environment": "live",
    "key_type": "full",
    "scopes": ["workspace:manage", "members:manage"],
    "mfa_code": "482019"
  }'

Erreurs

Toutes les erreurs suivent le format { "error": { "code": "...", "message": "...", "details": {...} } }. Le champ details est présent sur mfa_required et confirm_required pour lister les sensitive_scopes en cause.

{
  "error": {
    "code": "mfa_required",
    "message": "MFA code required for sensitive scopes",
    "details": {
      "sensitive_scopes": ["workspace:manage"],
      "mfa_method": "totp"
    }
  }
}

Bonnes pratiques

Voir aussi

• Votre premier transfert via l'API
• Idempotency : rejouer des requêtes en toute sécurité
• Webhooks : recevoir des événements en temps réel
• Gestion des rate-limits et quotas
• Tokens MCP : connecter Claude Desktop et Cursor
• Référence complète : GET /v1/api-keys
• Référence complète : POST /v1/api-keys