Rotation et révocation

Une clé d'API n'est pas éternelle. Vous la faites tourner (rotation) pour la remplacer périodiquement sans coupure, vous la révoquez immédiatement si elle fuite, et vous lui donnez une date d'expiration dès sa création. Ces trois opérations s'appuient sur la base https://api.coffrify.com/v1 et l'en-tête Authorization: Bearer <clé>.

Faire tourner une clé

La rotation crée une nouvelle clé qui hérite exactement des mêmes scopes, de la même liste d'IP autorisées et du même environnement que la clé d'origine. La valeur de la nouvelle clé n'est affichée qu'une seule fois dans la réponse. Par défaut, l'ancienne clé reste valide pendant une fenêtre de grâce (7 jours), le temps de déployer la nouvelle sans interrompre vos appels en cours. À l'échéance, l'ancienne clé est révoquée automatiquement.

Le corps accepte un seul champ facultatif, grace_days : le nombre de jours pendant lesquels l'ancienne clé reste active (valeur par défaut 7, maximum 30). Passez grace_days: 0 pour invalider l'ancienne clé immédiatement, sans période de recouvrement.

import { Coffrify } from '@coffrify/sdk';
 
const client = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const rotated = await client.apiKeys.rotate('key_id', { grace_days: 7 });
console.log(rotated.new_key);     // à enregistrer maintenant, affichée une seule fois
console.log(rotated.grace_until); // fin de la fenêtre de grâce

Révoquer une clé

La révocation désactive une clé immédiatement et de façon définitive : tout appel ultérieur présentant cette clé est rejeté. C'est l'action à déclencher dès qu'une clé est exposée (dépôt public, journal divulgué, poste compromis). L'opération est irréversible : pour retrouver un accès, créez une nouvelle clé.

Le corps est facultatif. Vous pouvez préciser un motif via reason, soit une valeur reconnue (manual, compromised, rotated, suspicious_activity, other), soit un texte libre (200 caractères maximum). Le motif est conservé avec la clé révoquée pour la traçabilité. La réponse confirme l'opération : { "id": "...", "object": "api_key", "revoked": true, "revoked_reason": "compromised" }.

import { Coffrify } from '@coffrify/sdk';
 
const client = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
await client.apiKeys.revoke('key_id', { reason: 'compromised' });

Donner une durée de vie limitée

La meilleure rotation est celle que vous n'avez pas à déclencher à la main. À la création d'une clé (POST /v1/api-keys), renseignez expires_in_days : une fois l'échéance passée, la clé cesse d'authentifier d'elle-même. Vous combinez ainsi expiration automatique et rotation planifiée. L'exemple ci-dessous émet une clé restreinte, au plus juste privilège, valable 90 jours.

curl -X POST https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer cof_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Connecteur de sauvegarde",
    "environment": "live",
    "key_type": "restricted",
    "scopes": ["transfers:read", "transfers:write"],
    "expires_in_days": 90
  }'

Suivre l'état d'une clé

Pour piloter une rotation ou confirmer qu'une clé compromise ne sert plus, interrogez GET /v1/api-keys/{id} : la réponse expose rotated_to_id, scheduled_revoke_at, revoked_at, revoked_reason, is_active et expires_at. Pour voir l'usage réel, GET /v1/api-keys/{id}/activity renvoie last_used_at, un histogramme par jour et les derniers appels. Si last_used_at n'a pas bougé depuis votre rotation, l'ancienne clé peut être coupée sans risque.

$ curl -s "https://api.coffrify.com/v1/api-keys/key_id/activity?days=7" \
    -H "Authorization: Bearer cof_live_votre_cle"

Bonnes pratiques

• Faites tourner régulièrement. Combinez expires_in_days à la création et un appel rotate planifié, en laissant une fenêtre de grâce le temps du déploiement.
• Coupez immédiatement en cas de fuite. Appelez rotate avec grace_days: 0, ou DELETE avec reason: "compromised". N'attendez jamais la fin d'une fenêtre de grâce pour une clé exposée.
• Une clé par usage. Un service, une intégration, un environnement : une clé dédiée. La révocation reste alors localisée et sans effet de bord.
• Privilège minimal. Émettez des clés restreintes (cof_rk_...) limitées aux seuls scopes nécessaires plutôt qu'une clé pleine, et bornez l'accès par allowed_ips quand c'est possible.
• Ne stockez jamais une clé en clair. Variables d'environnement et gestionnaires de secrets uniquement, jamais dans le code source ni dans un dépôt versionné.
• Surveillez l'usage. Contrôlez last_used_at et l'activité après chaque rotation, et auditez les clés inactives pour les révoquer.