Requête exemple
Réponse exemple
Crée un nouveau token MCP (Model Context Protocol) rattaché au workspace courant. Ces tokens, préfixés cof_mcp_live_* ou cof_mcp_test_*, servent à connecter des clients d'IA (Claude Desktop, Cursor, Cline, etc.) au serveur MCP Coffrify. Ils sont stockés dans une table distincte (coffrify_mcp_tokens) des clés API classiques (coffrify_api_keys) : ils partagent le même catalogue de scopes et la même sémantique d'expiration et de liste d'IP, mais leurs flux d'audit, d'activité et de révocation restent séparés pour ne pas mélanger les deux usages. Comportement notable : la valeur en clair du token n'est renvoyée qu'une seule fois, dans la réponse de création (champ token). Seule une empreinte SHA-256 est conservée côté serveur ; il est donc impossible de récupérer le secret ultérieurement. La réponse renvoie un statut HTTP 201.
Authentification
Requiert une clé API (ou un token MCP existant) authentifiée via Authorization: Bearer ... et portant le scope api_keys:manage. Ce scope contrôle la gestion des credentials du workspace : sans lui, l'appel échoue avec une erreur scope_missing (HTTP 403). Le token créé est automatiquement associé au workspace_id et au user_id du porteur de la clé appelante.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
| name | string | Oui | Nom lisible du token. Champ obligatoire : son absence déclenche une erreur validation_error (name is required). |
| description | string | Non | Description libre. Stockée telle quelle ; null si omise. |
| environment | string | Non | live ou test. Toute valeur autre que test est ramenée à live (valeur par défaut). Détermine le préfixe du token généré (cof_mcp_live_ ou cof_mcp_test_). |
| scopes | string[] | Non | Liste des scopes accordés au token. Par défaut ["transfers:read"] si omise. Un tableau vide est rejeté avec validation_error (at least one scope required). |
| client_hint | string | Non | Indice du client MCP cible. Valeurs autorisées : claude-desktop, claude, cursor, cline, continue, custom. Une valeur hors liste déclenche validation_error. null si omise ou chaîne vide. |
| expires_in_days | number | Non | Durée de validité en jours. Convertie en expires_at (date ISO = maintenant + N jours). Si omis, le token n'expire pas. |
| allowed_ips | string[] | Non | Liste blanche d'adresses IP autorisées à utiliser le token. Ignorée si le tableau est vide ou absent. |
| max_uses | number | Non | Nombre maximal d'utilisations du token. Si omis, aucune limite d'usage n'est appliquée. |
Réponse
Renvoie l'objet token créé. Les champs persistés incluent id, name, description, token_prefix (préfixe tronqué affichable, ex. cof_mcp_live_9a3f1c2b...), scopes, environment, allowed_ips, expires_at, max_uses, client_hint et created_at. Deux champs sont propres à la création et n'apparaîtront plus jamais ensuite : token, la valeur secrète en clair à copier immédiatement, et warning, un rappel explicite que le token ne sera plus affiché. Un évènement api_key.created (avec key_kind: "mcp_token") est émis en tâche de fond pour l'audit et les webhooks.
Erreurs
| Code | Statut | Quand | Comment résoudre |
|---|---|---|---|
| validation_error | 400 | name absent, scopes vide, ou client_hint hors liste autorisée. | Fournir un name, au moins un scope, et un client_hint parmi les valeurs autorisées. |
| missing_api_key | 401 | En-tête Authorization absent. | Envoyer Authorization: Bearer cof_live_... (ou un token MCP valide). |
| invalid_api_key | 401 | Credential mal formé ou introuvable. | Vérifier le préfixe du credential (cof_live_, cof_test_, cof_rk_live_, cof_mcp_live_, etc.) et qu'il existe. |
| revoked_api_key | 401 | Clé révoquée ou désactivée. | Régénérer ou réactiver une clé valide depuis la console. |
| expired_api_key | 401 | Clé appelante expirée. | Créer une nouvelle clé avec une date d'expiration future. |
| scope_missing | 403 | La clé appelante n'a pas le scope api_keys:manage. | Utiliser une clé portant api_keys:manage. |
| ip_not_allowed | 403 | IP de l'appelant hors de la liste blanche de la clé. | Appeler depuis une IP autorisée ou ajuster la liste d'IP de la clé. |
| rate_limited | 429 | Quota de requêtes du workspace dépassé (endpoint d'écriture). | Attendre la fenêtre indiquée par l'en-tête Retry-After puis réessayer. |
| internal_error | 500 | Échec d'insertion en base ou erreur serveur. | Réessayer ; si persistant, contacter le support avec le request_id. |
Voir aussi
GET/v1/mcp/tokensLister les tokens MCP du workspace (sans la valeur secrète).POST/v1/mcp/tokens/{id}/rotateFaire tourner un token MCP existant en générant un nouveau secret.DELETE/v1/mcp/tokens/{id}Révoquer un token MCP par son identifiant.