Un accès limité dont vous gardez la maîtrise

Les connexions sont des jetons d’espace

Les propriétaires et administrateurs créent les connexions dans Développeurs. Chacune est un jeton porteur lié à un espace et une audience : les jetons rest (sw_rest_...) fonctionnent uniquement pour /api/v1, et les jetons mcp (sw_mcp_...) uniquement pour /mcp.

Envoyez le jeton dans l’en-tête Authorization. Ne le mettez jamais dans une URL, une chaîne de requête, un fichier d’import ni un bundle de navigateur.

Authorization: Bearer sw_rest_...

Les portées limitent ce que votre rôle permet

Une connexion commence avec les portées de lecture seule : workspaces:read, catalog:read et worlds:read. N’ajoutez que le nécessaire, par exemple worlds:write pour les brouillons ou worlds:publish pour publier. GET /me exige account:read.

Une portée ne dépasse jamais les droits de la personne qui a créé le jeton, et ce rôle est relu à chaque requête. Les identifiants d’un autre espace renvoient 404 : un jeton ne peut pas découvrir ce qu’il ne doit pas voir.

Les portées sensibles sont facultatives

Les portées donnant accès aux adresses d’abonnés, messages de visiteurs, facturation, suppressions, écritures DNS, dépenses, changements d’équipe ou webhooks ne sont jamais précochées. En ajouter une demande d’abord une nouvelle connexion. Leurs outils MCP restent cachés jusqu’à ce que le jeton les possède.

Certaines actions restent totalement inaccessibles aux jetons : décider d’une approbation, supprimer ou restaurer des casas et comptes (une nouvelle connexion directe est requise et ces appels renvoient 403 reauthentication_required), et exporter des données.

Expiration, rotation et révocation

• Les jetons expirent après 30 jours par défaut et 90 jours au maximum.
• Seule une empreinte est stockée : un jeton perdu ne peut pas être réaffiché. Créez une nouvelle connexion.
• Pour une rotation, créez une connexion, faites-la utiliser par votre client, puis révoquez l’ancienne. La révocation s’applique dès la requête suivante, y compris au travail mis en file par un agent.

Erreurs possibles

• 401 : jeton absent, inconnu, expiré, révoqué ou destiné à l’autre audience.
• 403 insufficient_scope : une autorisation manque. context.required_scope la nomme et la réponse porte un en-tête WWW-Authenticate.
• 404 : la ressource n’existe pas dans l’espace du jeton.

OAuth n’est pas encore disponible

Les clients agents qui ne gèrent que la connexion OAuth ne peuvent pas encore se connecter. /.well-known/oauth-protected-resource/mcp ne liste donc aucun serveur d’autorisation. Utilisez un jeton de connexion dans les paramètres d’en-têtes du client.