Requête exemple
Réponse exemple
Crée une nouvelle clé d'API pour le workspace courant. Le secret en clair (champ key) n'est renvoyé qu'une seule fois dans cette réponse : il n'est jamais re-affichable ensuite, seul son hash SHA-256 est conservé en base. La clé peut être de type full (accès complet à tous les scopes) ou restricted (limitée aux scopes explicitement accordés). Comportement notable : toute clé full, ou toute clé restricted demandant au moins un scope à risque élevé, déclenche une étape de vérification renforcée (step-up) avant l'émission, soit par code MFA/TOTP, soit par une double confirmation explicite si la MFA n'est pas activée.
Authentification
Nécessite le scope api_keys:manage. L'appel doit en outre disposer d'un contexte utilisateur (session du tableau de bord ou Bearer token full-power) : un appel purement service-to-service sans userId est rejeté en 401 missing_api_key, car la validation par catalogue de scopes et le step-up MFA n'ont de sens que pour un utilisateur réel. Ce scope est lui-même classé à risque élevé : une clé restricted ne peut jamais l'accorder.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
| name | string | Oui | Nom lisible de la clé. Seul champ strictement obligatoire ; son absence renvoie 400 validation_error. |
| description | string | Non | Description libre. null si omis. |
| environment | string | Non | live ou test. Toute valeur autre que test est traitée comme live (défaut). Détermine le préfixe du secret (cof_live_* / cof_test_* ou cof_rk_live_* / cof_rk_test_*). |
| key_type | string | Non | full ou restricted. Toute valeur autre que restricted est traitée comme full (défaut). Une clé full accorde implicitement tous les scopes. |
| scopes | string[] | Non | Liste des scopes accordés. Défaut : ["transfers:read", "transfers:write"]. Ignoré dans les faits pour une clé full (qui couvre tout). |
| expires_in_days | number | Non | Durée de validité en jours. Converti en expires_at (ISO) = maintenant + N jours. Omis = clé sans expiration. |
| allowed_ips | string[] | Non | Liste d'IP autorisées à utiliser la clé. N'est enregistré que si le tableau est non vide ; sinon aucune restriction IP. |
| max_uses | number | Non | Nombre maximal d'utilisations de la clé. Omis = illimité. |
| mfa_code | string | Conditionnel | Requis au step-up si la MFA est activée : code TOTP à 6 chiffres, ou code de récupération (≥ 8 caractères) accepté en secours sans être consommé. |
| confirm_sensitive | boolean | Conditionnel | Requis au step-up si la MFA n'est PAS activée : doit valoir true pour confirmer explicitement l'émission d'une clé sensible. |
Réponse
Renvoie 201 avec l'objet de la clé créée : id, name, description, key_prefix (préfixe tronqué + 8 caractères hex visibles, sûr à afficher), key_type, scopes, environment, allowed_ips, expires_at, max_uses, created_at. S'y ajoutent deux champs propres à la création : key, le secret complet en clair (à stocker immédiatement, non re-affichable), et warning rappelant que la clé ne sera plus jamais montrée. Un événement api_key.created est émis en arrière-plan (webhooks).
Erreurs
| Code HTTP | Erreur | Quand | Résolution |
|---|---|---|---|
| 400 | validation_error | name manquant, ou clé restricted demandant un scope interdit | Fournir un name ; retirer les scopes interdits ou passer à une clé full. |
| 401 | missing_api_key | Aucun contexte utilisateur (userId) sur l'appel | Appeler via une session du tableau de bord ou un Bearer token full-power. |
| 401 | mfa_required | Scope sensible / clé full demandés avec MFA active mais mfa_code absent ou invalide | Renvoyer la requête avec un code TOTP à 6 chiffres valide (ou un code de récupération valide). details.sensitive_scopes liste les scopes en cause. |
| 401 | confirm_required | Scope sensible / clé full demandés alors que la MFA n'est pas activée et confirm_sensitive n'est pas true | Renvoyer avec confirm_sensitive: true, ou activer la MFA pour bénéficier du step-up TOTP. |
| 403 | forbidden | Le porteur ne possède pas le scope api_keys:manage | Utiliser une clé/un token disposant de api_keys:manage. |
| 500 | internal_error | Erreur d'insertion en base | Réessayer ; si persistant, contacter le support. |
Voir aussi
GET/v1/api-keysLister les clés d'API du workspace (sans jamais exposer le secret).POST/v1/api-keys/{id}/rotateFaire tourner le secret d'une clé existante en conservant sa configuration.GET/v1/api-keys/scopesRécupérer le catalogue des scopes disponibles, leur catégorie et leur niveau de risque.