Créer une clé API et choisir les bons scopes

L'API Coffrify utilise des clés porteur (Bearer tokens) pour authentifier chaque requête. Deux formats coexistent : les clés full (préfixe cof_live_ ou cof_test_) qui héritent de tous les scopes disponibles, et les clés restricted (préfixe cof_rk_live_ ou cof_rk_test_) dont les permissions sont limitées aux scopes que vous déclarez explicitement. La clé brute n'est retournée qu'une seule fois à la création : conservez-la immédiatement dans votre gestionnaire de secrets.

Authentification

Les endpoints GET /v1/api-keys et POST /v1/api-keys requièrent le scope api_keys:manage sur la clé appelante. Ce scope est classé risque élevé dans le catalogue Coffrify : il ne peut pas figurer dans les scopes d'une clé restricted. Si vous appelez ces routes avec une clé cof_rk_live_* dépourvue de ce scope, vous recevrez une erreur 403 forbidden_scope. Utilisez donc une clé cof_live_* (full) ou une cof_rk_live_* dont le scope api_keys:manage a été accordé explicitement au moment de sa création.

Corps de la requête (POST)

La création demande un nom, le type de clé (full ou restricted) et, pour une clé restreinte, la liste des scopes. Le tableau ci-dessous détaille les champs acceptés.

Exemples d'appels

L'exemple ci-dessous crée une clé restreinte avec un jeu de scopes minimal. Choisissez votre langage.

# Créer une clé restreinte pour lire et envoyer 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": "Service envoi fichiers",
    "key_type": "restricted",
    "environment": "live",
    "scopes": ["transfers:read", "transfers:write", "transfers:download"],
    "expires_in_days": 90,
    "description": "Cle utilisee par le service d envoi automatique."
  }'

{
  "id": "ak_01j9xkq2aabbccdd",
  "name": "Service envoi fichiers",
  "description": null,
  "key_prefix": "cof_rk_live_3f8a9b2c...",
  "key_type": "restricted",
  "scopes": ["transfers:read", "transfers:write", "transfers:download"],
  "environment": "live",
  "allowed_ips": null,
  "expires_at": "2026-09-04T14:23:10.000Z",
  "max_uses": null,
  "created_at": "2026-06-06T14:23:10.000Z",
  "key": "cof_rk_live_3f8a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
  "warning": "Save this key now - it will not be shown again."
}

Scopes disponibles (principaux)

Le tableau ci-dessous liste les principaux scopes et leur niveau de risque. Accordez uniquement ceux dont votre intégration a besoin (principe du moindre privilège).

• Faire votre premier appel API
• Révoquer ou faire pivoter une clé API
• Configurer un Webhook
• Référence : POST /v1/api-keys
• Référence : GET /v1/api-keys/scopes