service_token.create
Markdownv0.3.0
Frapper un jeton de compte de service : des portées nommées, une liste de projets, quatre-vingt-dix jours au plus. Rendu une seule fois.
- API
POST /v1/organizations/{organizationId}/service-tokens - CLI
bastide service_token create
EX-SEC-390, § 7.7.4. Le jeton agit sous son propre nom, sur les seuls projets nommés ici, au rang donné à chacun et dans la limite des portées nommées. Il ne reçoit que des portées que porte le jeton qui fait l'appel, et aucun rang plus haut que celui de l'appelant sur le projet. Celui qui le frappe en répond : si son compte est suspendu ou supprimé, le jeton n'ouvre plus rien. L'échéance est obligatoire, et ne se repousse pas : à son terme, il s'en frappe un autre. Cinquante jetons en vigueur au plus par organisation. Un compte de service lit, et ne mène que les écritures que la plateforme lui ouvre par leur nom — la page de chaque opération le dit.
| Propriété | Valeur |
|---|---|
| Niveau | organization |
| Rang minimal | admin |
| Rôle transversal | — |
| Portées | org:admin |
| Compte de service | ne la mène pas : elle est réservée à une personne |
| Réversibilité | R — réversible : exécution directe, tracée, annulable |
| Idempotence | une clé d'idempotence est acceptée : le rejeu rend la première réponse |
| Limites de débit, par jeton | 600 appels par 60 secondes (general), et 60 appels par 60 secondes (sensitive) |
API
POST /v1/organizations/{organizationId}/service-tokens — succès en 201.
| Paramètre | Où | Type | Requis | Description |
|---|---|---|---|---|
organizationId | chemin | texte, motif ^org_[0-9A-HJKMNP-TV-Z]{26}$ | oui | Identifiant de organisation |
Idempotency-Key | en-tête | texte, de 8 à 128 caractères | non | Clé d'idempotence. Un rejeu portant la même clé retourne le résultat initial sans nouvel effet de bord, et la réponse porte alors « Idempotency-Replayed: true ». Équivaut au champ « idempotencyKey » du corps ; les deux à la fois ne sont acceptés que s'ils sont identiques. |
name | corps | texte, de 1 à 80 caractères | oui | À quoi sert ce jeton : il se relit dans la liste. |
scopes | corps | liste de de 1 à 12 éléments — chaque élément : l'un de project:read, project:write, deploy:write, db:read, db:write, db:destructive, secrets:write, billing:read, billing:write, domain:write, audit:read, org:admin | oui | Ce que le jeton pourra faire. Au moins une portée ; aucune n'est implicite. |
expiresInDays | corps | entier, de 1 à 90 | oui | La durée de vie, en jours : de 1 à 90. Obligatoire. |
projects | corps | liste de de 1 à 20 éléments — chaque élément : objet (projectId, role) | oui | Les projets de cette organisation que le jeton ouvre, et le rang qu'il y tient. Rien d'autre ne lui est ouvert. |
idempotencyKey | corps | texte, de 8 à 128 caractères | non | Clé d'idempotence, obligatoire. Un rejeu portant la même clé rend le résultat initial, sans nouvel effet de bord. |
La réponse :
| Champ | Type | Description |
|---|---|---|
serviceTokenId | texte, motif ^tok_[0-9A-HJKMNP-TV-Z]{26}$ | Identifiant de jeton de compte de service |
name | objet (untrusted, source, content) | |
displayPrefix | texte | Les douze premiers caractères de l'identifiant : de quoi le reconnaître. |
scopes | liste de de 1 à 12 éléments — chaque élément : l'un de project:read, project:write, deploy:write, db:read, db:write, db:destructive, secrets:write, billing:read, billing:write, domain:write, audit:read, org:admin | Ce que ce jeton peut faire, dans la limite de ses rangs. |
projects | liste de 20 éléments au plus — chaque élément : objet (projectId, role) | La liste de projets, explicite : le jeton n'ouvre rien d'autre, et elle ne change pas — un autre périmètre, c'est un autre jeton. |
responsibleAccountId | texte, motif ^acc_[0-9A-HJKMNP-TV-Z]{26}$ | La personne qui en répond. Si son compte est suspendu ou supprimé, le jeton n'ouvre plus rien. |
state | l'un de active, revoked, expired, orphaned | « orphaned » : la personne qui en répond n'est plus un compte actif. Seul « active » ouvre un appel. |
createdAt | texte, format date-time | |
expiresAt | texte, format date-time | Au plus quatre-vingt-dix jours après sa création. |
token | texte | Le jeton, préfixé « tok_ ». Rendu une seule fois, jamais relu. |
undoToken | nul |
En-têtes de la réponse : RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotency-Replayed.
Autres réponses : 400, 401, 403, 404, 409, 429, 500, 503 — communes à toute opération.
Ligne de commande
bastide service_token create --organization-id <valeur> --name <valeur> --scopes <valeur> --expires-in-days <valeur> --projects <valeur>
| Option | Type | Requise | Défaut | Description |
|---|---|---|---|---|
--organization-id | texte | oui | — | Identifiant de organisation |
--name | texte | oui | — | À quoi sert ce jeton : il se relit dans la liste. |
--scopes | liste | oui | — | Ce que le jeton pourra faire. Au moins une portée ; aucune n'est implicite. |
--expires-in-days | nombre | oui | — | La durée de vie, en jours : de 1 à 90. Obligatoire. |
--projects | liste | oui | — | Les projets de cette organisation que le jeton ouvre, et le rang qu'il y tient. Rien d'autre ne lui est ouvert. |
--idempotency-key | texte | non | — | Clé d'idempotence, obligatoire. Un rejeu portant la même clé rend le résultat initial, sans nouvel effet de bord. |
La commande s'exécute sans confirmation.
MCP
Aucun outil : elle rend la valeur d'un secret, une seule fois, ou la refuse à tous : aucun outil MCP ne renvoie la valeur d'un secret, quelle que soit la portée du jeton (EX-MCP-070, EX-SEC-270).
Erreurs
| Code | Surface | Cause |
|---|---|---|
portee_non_detenue | les deux | Le jeton présenté ne porte pas une portée demandée pour le nouveau jeton : il ne peut donner que ce qu'il porte. |
rang_non_detenu | les deux | Le rang demandé pour le jeton, sur l'un des projets nommés, dépasse celui que l'appelant y tient : il ne peut donner que le sien, ou un rang plus bas. |
quota_de_jetons_de_service_atteint | les deux | L'organisation porte déjà le nombre publié de jetons de compte de service en vigueur : cinquante. |
idempotency_key_conflict | API | Deux clés d'idempotence différentes ont été présentées, dans le corps et dans l'en-tête. |
valeur_rendue_une_fois | API | Ce que l'opération crée n'est rendu qu'au premier appel : la plateforme n'en garde pas de copie, et un rejeu ne peut pas le rendre. |
S'y ajoutent les refus communs à toute opération — entrée invalide, authentification, autorisation, cible introuvable, conflit, limite de débit, indisponibilité — que le catalogue des erreurs décrit.
Exemples
Un jeton pour l'intégration continue : lecture d'un projet, trente jours :
{
"organizationId": "org_01JQ8ZK4M7NP2RSTVWXYZ34567",
"name": "intégration continue",
"scopes": [
"project:read"
],
"expiresInDays": 30,
"projects": [
{
"projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
"role": "reader"
}
],
"idempotencyKey": "jeton-de-service-ci-2026-10-06"
}