Renouveler une clé d'API

POST /v1/api-keys/{key_id}:rotate · autorisation api-keys:write · Idempotency-Key facultatif

Renouvelle une clé : crée une NOUVELLE clé avec le même nom, le même type, les mêmes autorisations et les mêmes allowed_cidrs, puis la renvoie. L'ancienne clé reste valide pendant overlap_hours, puis cesse de fonctionner.

Nouvelle clé. La réponse décrit la nouvelle clé ; rotated_from est l'identifiant de l'ancienne clé et key contient la clé brute une seule fois (Cache-Control: no-store). Déployez-la, puis laissez l'ancienne clé expirer.
Chevauchement. L'ancienne clé reçoit un revoked_at dans le futur et revoke_reason: rotated ; avec overlap_hours: 0, elle est révoquée immédiatement.
Pas d'élévation de privilèges. Une clé ne peut pas renouveler une clé dont les autorisations dépassent les siennes, et une clé restricted ne peut pas renouveler une clé secret. La nouvelle clé ne peut pas expirer après la clé appelante, même lorsqu'une clé se renouvelle elle-même (prolongez une durée de vie dans le tableau de bord), et une clé appelante avec allowed_cidrs ne peut renouveler que des clés limitées à des réseaux inclus dans les siens. Une clé créée dans le tableau de bord, ainsi que chaque clé renouvelée à partir de celle-ci, ne peut être renouvelée que par elle-même ou dans le tableau de bord (permission_escalation). La nouvelle clé conserve le created_by de l'ancienne clé ; la clé qui effectue le renouvellement est consignée dans le journal d'audit.
Rejeu idempotent. Un rejeu avec le même Idempotency-Key omet key et renvoie secret_redacted: true.

Requête

Paramètre	Dans	Description
`key_id`	chemin	Identifiant de la clé d'API (`key_…`).

Corps :

Le corps est facultatif ; sans lui, toutes les valeurs par défaut s'appliquent.

Champ	Type	Description
`overlap_hours`	entier	Facultatif, de 0 à 168, valeur par défaut 24. Nombre d'heures pendant lesquelles l'ancienne clé reste valide.
`expires_at`	chaîne (date-time)	Facultatif. Expiration de la NOUVELLE clé ; valeur par défaut : maintenant + 365 jours, au plus l'expiration de la clé appelante et au plus 730 jours.

Réponse

200 OK avec Cache-Control: no-store. L'objet de la NOUVELLE clé, accompagné de key.

{
  "id": "key_0000000000000000000000001z",
  "name": "ci",
  "type": "restricted",
  "permissions": ["users:read"],
  "allowed_cidrs": [],
  "last4": "xxxx",
  "created_by": "key_…",
  "created_at": "2026-10-01T10:00:00Z",
  "expires_at": "2027-10-01T10:00:00Z",
  "last_used_at": null,
  "last_used_ip": null,
  "rotated_from": "key_…",
  "revoked_at": null,
  "revoke_reason": null,
  "key": "<shown once>"
}

Erreurs

HTTP	`code`	Quand
401	`unauthenticated`	La clé est absente, invalide ou révoquée.
403	`insufficient_permissions`	La clé ne dispose pas de l'autorisation requise.
403	`permission_escalation`	La requête donnerait à une clé plus d'autorisations, une plage réseau plus large ou une expiration plus lointaine que la clé appelante, une clé `restricted` tente de créer, renouveler ou révoquer au-delà de ses propres autorisations, ou une autre clé tente de renouveler ou révoquer une clé créée dans le tableau de bord.
404	`not_found`	La clé n'existe pas dans cet environnement.
409	`conflict`	La clé est déjà révoquée, expirée ou déjà renouvelée (non active).
409	`api_key_limit_reached`	L'environnement compte déjà le maximum de 50 clés actives.
422	`validation_failed`	Le corps est invalide : `overlap_hours` est en dehors de 0 à 168, ou `expires_at` est dans le passé ou à plus de 730 jours.

Exemple

curl -X POST "https://api.eu.keenauth.com/v1/api-keys/key_0000000000000000000000001z:rotate" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours":24}'