Requête exemple
Réponse exemple
Effectue une rotation atomique d'une clé API : Coffrify génère une toute nouvelle clé qui hérite des mêmes scopes, du même type (`full` ou `restricted`), du même environnement (`live` ou `test`), de la même liste d'IP autorisées (`allowed_ips`) et du même quota `max_uses` que la clé source. Le comportement notable est la fenêtre de grâce : par défaut l'ancienne clé reste active pendant 7 jours (paramétrable, maximum 30 jours), ce qui permet de déployer la nouvelle clé sans coupure. À l'échéance, un cron quotidien révoque automatiquement l'ancienne clé. Avec grace_days: 0, l'ancienne clé est révoquée immédiatement. La réponse expose la clé en clair une seule et unique fois et l'opération émet l'événement webhook api_key.rotated.
Authentification
Requiert une clé API valide passée via Authorization: Bearer cof_live_... et porteuse du scope api_keys:manage. Une clé sans ce scope reçoit une erreur 403 scope_missing. Comme pour toute écriture, l'en-tête Idempotency-Key est pris en charge : une même clé d'idempotence rejoue la réponse mise en cache plutôt que de créer une seconde clé.
Corps de la requête
Le corps est optionnel : sans corps, la rotation s'effectue avec une fenêtre de grâce de 7 jours.
| Champ | Type | Requis | Description |
|---|---|---|---|
| grace_days | number (entier) | Non | Durée en jours pendant laquelle l'ancienne clé reste active avant révocation automatique. Défaut : 7. Valeur 0 = révocation immédiate de l'ancienne clé. Bornée côté serveur entre 0 et 30 (toute valeur supérieure est ramenée à 30, toute valeur invalide ou non finie retombe sur 7). |
L'identifiant de la clé à faire tourner est fourni dans le chemin ({id}), pas dans le corps. Les autres attributs de la nouvelle clé (scopes, IP, environnement, type, max_uses) ne sont pas modifiables ici : ils sont copiés à l'identique depuis la clé source. Le nom de la nouvelle clé est dérivé automatiquement sous la forme "<nom source> (rotated)".
Réponse
Réponse 201 Created. Le champ new_key contient la clé secrète complète en clair, affichée une seule fois : elle n'est jamais réexposée par la suite (seul son préfixe tronqué reste consultable). new_id est l'identifiant de la nouvelle clé créée, new_prefix son préfixe affichable (préfixe + 8 caractères hexadécimaux + ...), et old_id l'identifiant de la clé source. grace_until est l'horodatage ISO 8601 jusqu'auquel l'ancienne clé reste valide (égal à l'instant courant lorsque grace_days vaut 0). Le champ warning rappelle de sauvegarder la clé immédiatement et de basculer les appelants avant grace_until.
Erreurs
| Code HTTP | Code erreur | Quand | Résolution |
|---|---|---|---|
| 401 | missing_api_key | En-tête Authorization absent. | Ajouter Authorization: Bearer cof_live_.... |
| 401 | invalid_api_key | Format de clé non reconnu, ou clé introuvable. | Vérifier le préfixe (cof_live_ / cof_test_ / cof_rk_*) et la validité de la clé. |
| 401 | revoked_api_key / expired_api_key | La clé d'appel est révoquée, inactive ou expirée. | Émettre une nouvelle clé depuis app.coffrify.com/developer. |
| 403 | scope_missing | La clé d'appel ne porte pas le scope api_keys:manage. | Émettre une clé avec le scope api_keys:manage. |
| 404 | not_found | Aucune clé {id} dans ce workspace (mauvais id ou clé d'un autre workspace). | Vérifier l'id via GET /v1/api-keys ; une clé n'est visible que dans son workspace. |
| 429 | rate_limited | Quota de requêtes/minute du workspace dépassé (endpoint write). | Respecter l'en-tête Retry-After puis réessayer. |
| 500 | internal_error | Échec en base lors de la lecture, de l'insertion ou de la planification de révocation. | Réessayer ; si persistant, contacter le support avec le request_id renvoyé. |
Voir aussi
GET/v1/api-keysLister les clés du workspace pour retrouver l'id à faire tourner et suivre les clés en cours de rotation.DELETE/v1/api-keys/{id}Révoquer manuellement une clé (utile pour couper l'ancienne avant la fin de la fenêtre de grâce).POST/v1/webhooks/{id}/rotate-secretFaire tourner le secret de signature d'un webhook, sur un modèle de rotation analogue.