SpuntoSpunto/Docs

Clés d’API

Générez des tokens Bearer à scopes pour un accès sans navigateur — scripts, pipelines de CI et agents IA.

Les clés d’API sont des tokens Bearer de longue durée pour accéder à l’API Spunto par programme — pour des scripts, des pipelines de CI ou des agents IA qui doivent piloter la plateforme sans session de navigateur. Chacune est limitée à une seule organisation et à un ensemble précis de permissions, et se révoque indépendamment de la session de connexion de quiconque.

Remarque

Pour tout usage sans navigateur, préférez une clé d’API à un JWT de session que vous signeriez vous-même — elle a des scopes, un nom, se révoque seule, et ne fait jamais expirer la session dashboard de la personne qui l’a créée.

1

Ouvrir les réglages de l’organisation

Une clé appartient toujours à une organisation. Dans le dashboard de l’organisation sur laquelle la clé doit agir, ouvrez Settings → API keys.

2

Choisir le type de propriétaire

Une clé Personal agit en votre nom — elle cesse de fonctionner si vous n’êtes plus membre de l’org. Une clé Org (service account) appartient à l’organisation elle-même et continue de fonctionner même si son créateur s’en va ; en créer une demande le rôle admin ou owner.

3

Sélectionner les scopes

Choisissez l’ensemble de scopes le plus étroit dont le script ou l’agent a réellement besoin (voir Scopes plus bas).

4

Copier le token

Le token complet (spk_...) n’est affiché qu’une fois, juste après la création. Rangez-le en lieu sûr — Spunto n’en garde qu’un hash, il ne peut donc plus être affiché. Si vous le perdez, révoquez la clé et créez-en une autre.

Personnelle (ownerType: "user")Service account de l’org (ownerType: "org")
Agit en tant queVousL’organisation
Qui peut la créerTout membre de l’org, pour lui-mêmeadmin / owner seulement
Survit au départ de son créateurNon — liée à votre appartenanceOui
Usage typiqueScripts personnels, votre propre outillage CLICI au long cours, agent autonome déployé en prod

Les scopes sont larges et organisés par ressource, sous la forme resource:action. Une requête doit porter au moins un scope correspondant (ou le joker *) pour passer — les sessions ouvertes par la connexion au dashboard (JWT/cookie) ne sont pas concernées et ont toujours un accès complet ; les scopes ne s’appliquent qu’aux clés d’API.

ScopeDonne accès à
*Tous les scopes ci-dessous — accès complet
projects:readLister/lire les projets, historique des versions
projects:writeCréer/modifier/supprimer des projets, restaurer des versions
workers:readLister/lire les sandboxes, leurs ports, leurs snapshots
workers:writeCréer/démarrer/arrêter/reconstruire/supprimer des sandboxes
workers:execLancer des commandes (POST .../exec) et des sessions de terminal — un accès shell dans une sandbox
tasks:readLister/lire les tâches, leurs événements et leurs diffs
tasks:writeDéléguer, répondre, accepter et abandonner des tâches — cela lance une session d’agent, c’est donc aussi un accès de niveau shell

Attention

workers:exec et tasks:write sont volontairement séparés des scopes génériques de lecture/écriture — ils donnent un accès shell. Ne les mettez pas dans une clé de « supervision en lecture seule ».

Une requête est rapprochée ainsi : GET → :read, toute autre méthode HTTP → :write, sauf les endpoints de commandes et de terminal sous /sandboxes/..., qui exigent toujours :exec, quelle que soit la méthode.

Envoyez-la comme un token Bearer standard — exactement comme un JWT de session :

curl -H "Authorization: Bearer spk_..." \
  https://spunto.net/api/orgs/{orgId}/projects
curl -X POST \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "{projectId}", "appId": "spunto-cloud", "name": "ci" }' \
  https://spunto.net/api/orgs/{orgId}/sandboxes

Une requête dont la clé est absente, malformée, révoquée ou expirée reçoit 401 Unauthorized. Une requête avec une clé valide mais sans le scope nécessaire reçoit 403 Forbidden.

Attention

Une clé d’API ne peut ni créer, ni lister, ni révoquer d’autres clés d’API — aucune escalade de clé à clé n’est possible. Gérer les clés demande une vraie session (connexion par le navigateur), le même niveau de confiance qu’inviter un membre.

GET    /api/orgs/:orgId/api-keys           List keys (token values are never returned, only a `tokenPrefix`)
POST   /api/orgs/:orgId/api-keys           Create a key — { name, ownerType, scopes } → { ...key, token }
DELETE /api/orgs/:orgId/api-keys/:keyId    Revoke a key

Les schémas complets des requêtes et des réponses (dont les formes ApiKey/ApiKeyCreated) sont dans la référence interactive — cherchez le tag ApiKeys sur /api/docs, ou parcourez le spec brut sur /openapi.json.

curl -X DELETE \
  -H "Authorization: Bearer <session token, not an API key>" \
  https://spunto.net/api/orgs/{orgId}/api-keys/{keyId}

La révocation est immédiate — la toute prochaine requête faite avec ce token reçoit 401. La ligne de la clé n’est pas supprimée, seulement marquée révoquée : elle reste visible (et auditable) dans la liste.

  • Pas encore d’expiration. Une clé est valable jusqu’à sa révocation — il n’y a aujourd’hui aucune option « expire dans 90 jours », ni dans le dashboard ni dans l’API.
  • Pas de restriction par projet. Un scope comme workers:write s’applique à tous les projets de l’org, pas à un seul.
  • Pas de limitation de débit. Un script ou une boucle d’agent qui s’emballe avec une clé d’API n’est borné que par les mêmes limites que tout le reste — c’est-à-dire aucune pour l’instant.

Conseil

Pour le cas des agents IA en particulier (créer des sandboxes, lancer des commandes, lire leur sortie), voir le guide Agents IA — il déroule tout le cycle de vie avec une clé d’API.

PrécédentRéférence de l’APISuivantServeur MCP