Authentification

Tous les appels à l'API REST de Coffrify sont authentifiés par une clé secrète que vous passez dans l'en-tête HTTP Authorization. La clé identifie votre workspace, l'environnement ciblé (production, test ou sandbox) et l'ensemble des permissions accordées. Cette page décrit le format des clés, leur transmission, les scopes disponibles, la rotation, la révocation et le stockage sécurisé. Les clés se créent et se gèrent depuis votre tableau de bord développeur, ou par l'API elle-même si vous disposez d'une clé habilitée.

En-tête Authorization

Chaque requête doit porter votre clé secrète dans l'en-tête Authorization, préfixée par Bearer. La base de l'API est https://api.coffrify.com/v1. Toutes les communications passent en HTTPS : un appel en clair est refusé.

curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_VOTRE_CLE_SECRETE"

Avec le SDK JavaScript/TypeScript officiel (paquet coffrify), il vous suffit de fournir la clé à l'initialisation : l'en-tête est ajouté automatiquement à chaque appel.

import { Coffrify } from "coffrify";
 
const coffrify = new Coffrify({
  apiKey: process.env.COFFRIFY_API_KEY,
});

Types et préfixes de clés

Le préfixe de la clé indique à la fois sa nature et son environnement. Vous reconnaissez donc d'un coup d'œil si une clé vise la production, le test ou le sandbox, et si elle est de pleine puissance ou restreinte.

Clés restreintes et scopes

Une clé de pleine puissance (cof_live_ / cof_test_) donne accès à l'ensemble des opérations du workspace. Pour le principe du moindre privilège, préférez une clé restreinte (cof_rk_) à laquelle vous attribuez uniquement les scopes nécessaires. Un appel exigeant un scope absent de la clé renvoie une erreur 403 scope_missing. Les scopes les plus courants :

Si vous créez une clé restreinte sans préciser de scopes, elle reçoit par défaut transfers:read et transfers:write. Une clé restreinte ne peut jamais accorder les scopes d'administration les plus sensibles, comme api_keys:manage : pour ceux-là, utilisez une clé de pleine puissance.

Créer une clé par l'API

La clé qui crée d'autres clés doit porter le scope api_keys:manage. Vous indiquez le nom, l'environnement (live ou test), le type (full ou restricted) et, pour une clé restreinte, la liste des scopes.

curl https://api.coffrify.com/v1/api-keys \
  -H "Authorization: Bearer cof_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cle-creation-2026-06-10-001" \
  -d '{
    "name": "Service de transfert",
    "environment": "live",
    "key_type": "restricted",
    "scopes": ["transfers:read", "transfers:write"]
  }'

Le champ key de la réponse contient la valeur secrète complète : c'est la seule occasion de la lire. Le champ key_prefix est l'identifiant abrégé que vous retrouverez ensuite dans la liste de vos clés.

Rotation

La rotation génère une nouvelle clé reprenant exactement les scopes, l'environnement et les restrictions d'origine, tout en gardant l'ancienne active pendant une fenêtre de grâce (grace_days, 7 jours par défaut, 30 au maximum). Vous déployez la nouvelle clé sans interruption, puis l'ancienne est révoquée automatiquement à l'échéance. Passez grace_days: 0 pour révoquer l'ancienne immédiatement.

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

La réponse fournit new_key (la nouvelle valeur secrète, à copier sur-le-champ), new_id, old_id et grace_until, la date limite avant laquelle vous devez avoir basculé tous vos appels.

Révocation

Si une clé est compromise ou n'a plus lieu d'être, révoquez-la sans délai. La révocation est immédiate et définitive : tout appel ultérieur portant cette clé est refusé. Vous pouvez joindre un motif (reason).

$ curl -X DELETE https://api.coffrify.com/v1/api-keys/key_123 \
    -H "Authorization: Bearer cof_live_VOTRE_CLE" \
    -H "Content-Type: application/json" \
    -d '{"reason": "compromised"}'

Stockage sécurisé des clés

Une clé secrète donne accès aux données de votre workspace : traitez-la avec le même soin qu'un mot de passe. Quelques règles simples :

• Conservez les clés dans un gestionnaire de secrets ou des variables d'environnement, jamais en dur dans le code.
• Ne les versionnez pas : excluez les fichiers .env du contrôle de version et ne les écrivez pas dans les journaux.
• Ne les exposez jamais dans du code côté navigateur ni dans une application mobile : une clé secrète reste strictement côté serveur.
• Attribuez à chaque service sa propre clé restreinte, limitée aux scopes utiles, pour pouvoir la révoquer isolément.
• Faites tourner régulièrement les clés de production, et immédiatement à la moindre suspicion de fuite.

Erreurs d'authentification

Une authentification qui échoue renvoie un statut HTTP 401 ou 403 et un corps JSON décrivant l'erreur. Le champ request_id est précieux si vous contactez le support.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key not found.",
    "request_id": "req_..."
  }
}