Clés restreintes

Une clé restreinte est une clé API volontairement bridée : au lieu de donner accès à tout le workspace, elle ne porte qu'un sous-ensemble de scopes que vous choisissez, et elle ne peut jamais obtenir les permissions les plus sensibles. C'est l'outil recommandé pour toute intégration ciblée : un script qui ne fait qu'envoyer des transferts, un connecteur tiers qui n'a besoin que de lire l'audit, une fonction serverless qui n'expose qu'un seul flux de réception. Vous reconnaissez ces clés à leur préfixe cof_rk_ (pour *restricted key*), par opposition aux clés pleines cof_live_ et cof_test_.

Le principe de moindre privilège

Accordez à chaque clé le strict nécessaire. Un service qui dépose des fichiers n'a besoin que de transfers:write ; il n'a aucune raison de pouvoir lire l'audit, gérer les membres ou exporter les données RGPD. En isolant chaque intégration dans sa propre clé restreinte, vous obtenez trois bénéfices concrets : un rayon d'explosion minimal en cas de compromission, une révocation chirurgicale (couper une intégration sans toucher aux autres), et une traçabilité claire (chaque clé apparaît sous son propre nom dans le journal d'audit).

Créer une clé restreinte

Une clé restreinte se crée via l'endpoint de gestion des clés, en passant key_type: "restricted" et la liste exacte des scopes souhaités. La clé en clair n'est renvoyée qu'une seule fois, dans le champ key de la réponse : copiez-la immédiatement dans votre gestionnaire de secrets, elle ne sera plus jamais affichée.

curl -X POST https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer cof_live_VOTRE_CLE_PLEINE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Intégration dépôt CI",
    "environment": "live",
    "key_type": "restricted",
    "scopes": ["transfers:read", "transfers:write"],
    "allowed_ips": ["203.0.113.10"],
    "expires_in_days": 90
  }'

La réponse contient l'identifiant de la clé, son key_prefix (préfixe visible, sûr à journaliser), les scopes retenus, l'allowed_ips, l'éventuelle expires_at, et la clé secrète complète dans key. Pour une clé restreinte en production, ce préfixe ressemble à cof_rk_live_a1b2c3d4... ; en environnement de test, à cof_rk_test_....

{
  "id": "key_8f3a1c",
  "name": "Intégration dépôt CI",
  "key_prefix": "cof_rk_live_a1b2c3d4...",
  "key_type": "restricted",
  "scopes": ["transfers:read", "transfers:write"],
  "environment": "live",
  "allowed_ips": ["203.0.113.10"],
  "expires_at": "2026-09-08T10:00:00Z",
  "key": "cof_rk_live_a1b2c3d4e5f6...",
  "warning": "Save this key now - it will not be shown again."
}

Choisir les scopes

Les scopes suivent la forme ressource:action (par exemple transfers:write, audit:read, webhooks:manage). Listez uniquement ceux dont votre intégration a besoin. Le tableau ci-dessous donne quelques jeux de scopes typiques selon le cas d'usage.

Certains scopes restent sensibles même sur une clé restreinte (par exemple audit:export, gdpr:export, sessions:manage, domains:manage). Les inclure est autorisé, mais déclenche une étape de vérification MFA au moment de la création : fournissez alors un mfa_code dans le corps de la requête. À noter aussi : l'appel de création lui-même requiert le scope api_keys:manage, vous devez donc émettre vos clés restreintes depuis une clé pleine (ou une session du tableau de bord) habilitée à gérer les clés.

Restreindre par adresse IP

En plus des scopes, vous pouvez verrouiller une clé à une liste d'adresses IP via allowed_ips. Toute requête provenant d'une IP absente de la liste est rejetée, même si la clé et ses scopes sont valides. C'est une seconde barrière idéale pour les intégrations qui tournent depuis des serveurs à IP stable (passerelle de sortie, runner CI, fonction edge derrière une IP fixe). Laissez le champ vide pour autoriser toutes les origines réseau.

curl -X POST https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer cof_live_VOTRE_CLE_PLEINE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Edge function réception",
    "key_type": "restricted",
    "scopes": ["intake:read"],
    "allowed_ips": ["203.0.113.10", "198.51.100.4"]
  }'

Utiliser la clé

Une clé restreinte s'utilise exactement comme n'importe quelle clé : dans l'en-tête Authorization: Bearer. La seule différence est qu'un appel hors de ses scopes renvoie une erreur d'autorisation plutôt qu'un succès. Côté SDK, il suffit de passer la clé restreinte à apiKey.

$ curl https://api.coffrify.com/v1/transfers \
    -H "Authorization: Bearer cof_rk_live_a1b2c3d4e5f6..."
{ "object": "list", "data": [ ... ], "has_more": false }

Cycle de vie : expiration et rotation

Donnez une durée de vie à vos clés d'intégration avec expires_in_days : une clé expirée cesse d'être acceptée automatiquement, ce qui limite l'exposition d'un secret oublié. Pour renouveler une clé sans interruption de service, utilisez la rotation : elle émet une nouvelle clé en conservant les mêmes scopes, le même allowed_ips et le même type, tout en laissant l'ancienne valide pendant une fenêtre de grâce (grace_days, 7 jours par défaut, 30 maximum, 0 pour révoquer immédiatement).

curl -X POST https://api.coffrify.com/v1/api-keys/key_8f3a1c/rotate \
  -H "Authorization: Bearer cof_live_VOTRE_CLE_PLEINE" \
  -H "Content-Type: application/json" \
  -d '{ "grace_days": 7 }'

Déployez la nouvelle clé sur tous vos appelants avant grace_until, puis laissez l'ancienne se révoquer d'elle-même. Pour fermer une intégration définitivement, révoquez sa clé avec DELETE /v1/api-keys/{id} : l'opération est ciblée et n'affecte aucune autre clé du workspace.