Effectuer une rotation de clé API sans coupure de service

La rotation régulière des clés API est une bonne pratique de sécurité essentielle. L'endpoint POST /v1/api-keys/{id}/rotate génère une nouvelle clé avec exactement les mêmes scopes, liste d'IP autorisées et environnement que la clé source, puis place l'ancienne clé en révocation différée. Pendant la fenêtre de grâce (7 jours par défaut, 0 à 30 jours au choix), les deux clés restent actives simultanément : vous pouvez déployer la nouvelle valeur dans vos systèmes sans jamais couper le flux. À l'expiration de la fenêtre, un cron quotidien révoque automatiquement l'ancienne clé et déclenche l'événement api_key.rotated.

Authentification

Les deux endpoints exigent le scope api_keys:manage. Ce scope est considéré comme sensible : il ne peut pas être accordé à une clé de type restricted (préfixe cof_rk_live_… ou cof_rk_test_…). Pour appeler ces routes, vous devez utiliser une clé full-power (cof_live_… ou cof_test_…) ou une clé restricted qui possède explicitement api_keys:manage, ce qui est impossible par construction. Transmettez votre clé dans l'en-tête Authorization: Bearer <votre-clé>.

Corps de la requête

Le corps précise surtout la fenêtre de grâce (grace_days) pendant laquelle l'ancienne clé reste valide. Le tableau ci-dessous détaille les champs acceptés.

Exemples d'appel

L'exemple ci-dessous effectue une rotation avec une fenêtre de grâce, puis vérifie l'état de l'ancienne clé. Choisissez votre langage.

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

Réponse (HTTP 201)

La réponse renvoie la nouvelle clé en clair (new_key), affichée une seule et unique fois : stockez-la immédiatement. Elle expose aussi l'échéance de révocation de l'ancienne clé.

{
  "new_key":    "cof_live_9f3e1a2b7c4d8e0f1a2b3c4d5e6f7g8h",
  "new_id":     "key_01jzabc123defgh456",
  "new_prefix": "cof_live_9f3e1a2b...",
  "old_id":     "key_01jxxxxxxxxxxxxxxxx",
  "grace_until": "2026-06-13T14:30:00.000Z",
  "warning": "Save this key now - it will not be shown again. Roll callers to the new key before grace_until."
}

Erreurs

Les erreurs portent sur le scope api_keys:manage manquant, une clé introuvable ou déjà en rotation. Le tableau ci-dessous indique la résolution.

Bonnes pratiques

Vérifier l'état de l'ancienne clé

Après la rotation, vous pouvez inspecter l'ancienne clé via GET /v1/api-keys/{old_id}. Les champs scheduled_revoke_at, rotated_to_id et is_active reflètent l'état en temps réel. Tant que is_active vaut true et que revoked_at est null, l'ancienne clé continue d'accepter les requêtes.

{
  "id":                  "key_01jxxxxxxxxxxxxxxxx",
  "name":                "Clé production webhook",
  "key_prefix":          "cof_live_a1b2c3d4...",
  "key_type":            "full",
  "scopes":              ["transfers:read", "transfers:write"],
  "environment":         "live",
  "is_active":           true,
  "scheduled_revoke_at": "2026-06-13T14:30:00.000Z",
  "rotated_to_id":       "key_01jzabc123defgh456",
  "revoked_at":          null,
  "recent_activity":     []
}

Voir aussi

• Créer une clé API
• Révoquer une clé API
• Comprendre les scopes API
• Recevoir des événements via Webhook
• Référence : api_key.rotated