Space Access Token

Le Space Access Token est un jeton qui permet de lire et d'écrire du contenu au sein d'un seul Space. Il peut créer, modifier et supprimer du contenu via la CMA, et sert aussi à appeler la lecture CDA et l'Upload. Lors de son émission, il est lié à un seul SpaceRole, et ce rôle définit ce que le jeton peut faire et jusqu'où (quels Content Type il peut manipuler et par quelles actions).

Contrairement au Delivery Access Token, qui est en lecture seule, ce jeton permet aussi l'écriture. En revanche, contrairement au Personal Access Token, qui est lié à l'ensemble d'un compte utilisateur, il se limite à un seul Space et ne peut accéder ni aux paramètres du Space, ni au plan de l'organisation ou du compte, ni à un autre Space. Dans la CMA, le Space Access Token est une ressource enfant du Space, et son chemin repose sur /spaces/{spaceId}/space-access-tokens. Selon votre service, vous décidez de placer ce jeton sur un serveur ou dans un client exposé (par exemple pour une écriture anonyme). Comme il s'agit d'un jeton puissant doté du droit d'écriture, vous assurez la sécurité en restreignant le rôle qui lui est lié à la portée d'exposition de l'endroit où le jeton est placé (voir Sécurité : liaison du rôle adaptée à la portée d'exposition ci-dessous).

Structure de la ressource

Voici la réponse obtenue lors de la création d'un Space Access Token. L'objet sys (propriétés système) contient la valeur et la portée du jeton, et le corps comporte name, description et allowedReferrers.

{
  "sys": {
    "id": "7WpR4mKq2bTnXfLc8Vd3HsJ9gEyAo",
    "type": "SpaceAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQwYT32LnU", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-19T02:15:38.472Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-19T02:15:38.472Z",
    "accessToken": "SPCATq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["SPACE_ACCESS_TOKEN"]
  },
  "allowedReferrers": [],
  "description": "Jeton serveur pour l'enregistrement et la modification des produits de la boutique de vêtements",
  "name": "Serveur backend des produits"
}

Clés principales :

• sys.id : identifiant unique du Space Access Token. Il s'insère dans le {spaceAccessTokenId} des chemins de consultation, de modification et de suppression d'un élément unique.
• sys.space : le Space auquel ce jeton appartient. Le jeton ne fonctionne que dans ce seul Space.
• sys.accessToken : valeur secrète du jeton utilisée pour les appels d'API. Elle commence par SPCAT et, comme la même valeur réapparaît à l'identique lors d'une consultation après émission, il faut veiller à son exposition (voir la section sécurité ci-dessous).
• sys.scopes : portée des autorisations du jeton. Pour un Space Access Token, c'est toujours ["SPACE_ACCESS_TOKEN"] à l'émission.
• sys.user : utilisateur dédié qui est le sujet des autorisations de ce jeton. Il est créé automatiquement lors de l'émission, et les autorisations du SpaceRole lié sont accordées à cet utilisateur. Autrement dit, les autorisations effectives du jeton proviennent de cet utilisateur. C'est un utilisateur différent de la personne qui a réellement émis ce jeton (sys.createdBy).
• name : nom du jeton défini lors de la création (par exemple : Serveur backend des produits).
• description : description du jeton (facultatif).
• allowedReferrers : liste qui restreint les origines depuis lesquelles ce jeton peut être appelé. Une liste vide ne restreint rien. Dans l'exemple ci-dessus, la liste est laissée vide parce que ce jeton est appelé depuis un serveur (pour les règles d'écriture et le mode de contrôle, voir Règles d'écriture des origines et Contrôle du Referer).

role (le SpaceRole à lier) est une valeur d'entrée envoyée uniquement dans le corps de la requête de création ; elle n'est pas incluse dans la ressource de réponse. Le rôle lié est attribué à l'utilisateur propre à ce jeton (le sys.user de la réponse), si bien qu'il ne réapparaît pas sous la forme d'un champ role dans la réponse de consultation. Dans l'exemple ci-dessus, accessToken est une valeur secrète, donc elle a été remplacée par une chaîne d'exemple. En réalité, il s'agit d'une chaîne longue et opaque commençant par SPCAT, et la même valeur réapparaît même si on la consulte de nouveau après émission.

Propriétés système (sys)

Chaque Space Access Token place dans l'objet sys des propriétés système communes ainsi que des propriétés propres au jeton. space, user, createdBy et updatedBy se présentent sous la forme Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Propriétés du corps :

Entrée réservée au corps de la requête de création :

Sécurité : liaison du rôle adaptée à la portée d'exposition

Le Space Access Token est un jeton puissant qui permet aussi l'écriture. Le SpaceRole auquel il est lié constitue à la fois la frontière de ce que ce jeton peut faire et sa frontière de sécurité. Vous décidez selon votre service de placer ce jeton sur un serveur ou dans un client exposé (par exemple pour une écriture anonyme) ; la sécurité s'assure non pas par « l'endroit où on le cache », mais en restreignant le rôle lié à la portée d'exposition.

• Dans le role de la requête de création, indiquez le sys.id d'un SpaceRole restreint qui n'autorise que les actions nécessaires à cet usage. Pour un jeton serveur destiné à l'enregistrement de produits, liez un rôle qui n'autorise que la lecture et l'écriture sur le Content Type produit ; pour un jeton public d'écriture anonyme, liez un rôle qui n'autorise que la création (create) sur le Content Type des publications. Vous liez ainsi au strict minimum, en fonction de la portée d'exposition.
• Plus un jeton est exposé dans un client public, plus vous devez restreindre son rôle. N'autorisez que ce que vous pouvez assumer même en cas de fuite de ce jeton. Ne liez pas le rôle Administrator ni un rôle d'écriture étendu à un jeton public. De plus, n'utilisez pas par inadvertance le premier élément de la liste des SpaceRole : indiquez explicitement le sys.id du rôle restreint voulu.
• Si le jeton est appelé depuis un navigateur, restreignez aussi le point d'appel avec allowedReferrers. Le rôle lié définit ce que ce jeton peut faire, et cette liste définit depuis où le jeton peut être appelé (voir Contrôle du Referer).
• Pour une diffusion en lecture seule exposée aux visiteurs, le Delivery Access Token, dépourvu du droit d'écriture, est plus adapté. N'utilisez le Space Access Token que lorsque l'écriture est nécessaire, et restreignez son rôle à la portée d'exposition.
• accessToken est une valeur secrète qui se consulte avec la même valeur même après l'émission. Là où il n'a pas à être exposé, ne le laissez pas en clair dans le code, les journaux, le stockage ou les messages d'erreur ; en cas de soupçon de fuite, supprimez-le pour l'invalider et remplacez-le par un nouveau jeton.

États et contraintes

Contraintes de valeur à respecter lors de la création et de la modification.

Règles relatives à la liaison et aux permissions :

• Le role à lier doit réellement exister dans ce Space. Si vous indiquez le sys.id d'un rôle inexistant, la création est refusée.
• L'appelant ne peut lier que les rôles qu'il détient lui-même dans ce Space. Cette contrainte empêche d'accorder au jeton des privilèges plus élevés en liant un rôle que l'appelant ne détient pas ; une demande de création qui l'enfreint est refusée. Toutefois, l'administrateur de ce Space (le détenteur du rôle Administrator) n'est pas soumis à cette contrainte et peut lier n'importe quel rôle.
• Le Space Access Token est une ressource soumise à une limite de nombre. Si vous dépassez la limite d'émission de la formule actuelle, la création est refusée. Pour les limites par formule, consultez Tarifs.
• L'émission et la gestion (création, consultation, modification, suppression) exigent la présence de SETTING_SPACE_ACCESS_TOKEN dans le settings du rôle de l'appelant. Comme il s'agit d'une action distincte de SETTING_DELIVERY_ACCESS_TOKEN, qui émet le Delivery Access Token en lecture seule, vous pouvez n'accorder que le droit d'émettre le jeton de diffusion tout en interdisant l'émission de ce jeton (voir SpaceRole).
• Cette API n'est appelée qu'avec une session de connexion à la console ou un Personal Access Token. Un Space Access Token ne peut pas lui-même créer un autre Space Access Token, et cela reste vrai même si vous placez SETTING_SPACE_ACCESS_TOKEN dans le rôle lié.

Règles d'écriture des origines

Chaque élément de allowedReferrers est une chaîne qui désigne une seule origine depuis laquelle l'appel est autorisé. Écrivez cette chaîne sous la forme suivante.

"allowedReferrers": [
  "https://shop.example.com",
  "https://*.shop.example.com",
  "http://localhost:3000"
]

La liste accepte au maximum 50 éléments, et une même origine ne peut pas y figurer deux fois. Les règles que chaque élément doit respecter sont les suivantes.

• Le schéma doit être https. Le schéma http n'est admis que pour localhost, 127.0.0.1 et [::1].
• Le caractère générique s'écrit uniquement comme une seule étiquette *. placée en tête. Il ne peut pas s'employer dans le chemin.
• Écrivez l'hôte en ASCII. Indiquez un domaine internationalisé en notation Punycode.
• Le port va de 1 à 65535. S'il est omis, c'est le port par défaut du schéma qui s'applique (443 pour https, 80 pour http).
• Si vous indiquez un chemin, la requête ne passe que lorsque le chemin de la requête est exactement le même. Comme le navigateur envoie le chemin en encodage pourcent, n'écrivez le chemin qu'en ASCII.
• Un élément portant des informations d'utilisateur (user@), une requête (?) ou un fragment (#) est refusé.

Ce contrôle s'applique aux trois chemins : la création, la modification complète et la modification partielle. S'il subsiste ne serait-ce qu'un élément contraire aux règles, la liste n'est pas enregistrée et la requête est refusée ; l'un des éléments en infraction est signalé dans le motif de l'erreur (voir Erreurs).

Contrôle du Referer

Après l'émission, chaque fois que vous appelez l'API avec ce jeton, allowedReferrers est appliqué à la requête pour décider si elle passe.

• Si la liste est vide, aucune restriction ne s'applique. La requête passe depuis n'importe quelle origine.
• Dès que la liste comporte au moins un élément, la décision se prend sur la valeur de l'en-tête Referer de la requête. L'en-tête Origin n'est pas examiné.
• Si l'en-tête Referer est absent ou si sa valeur est vide, la requête est refusée. Laissez la liste vide pour un jeton destiné à des endroits qui n'envoient pas de Referer, comme les appels entre serveurs.
• Pour passer, le schéma, l'hôte et le port du Referer doivent tous être identiques à ceux d'un élément de la liste. Si cet élément comporte un chemin, le chemin doit lui aussi être identique.
• https://*.shop.example.com couvre tous les hôtes qui se terminent par .shop.example.com, comme admin.shop.example.com, mais ne couvre pas shop.example.com lui-même. Pour autoriser les deux, ajoutez https://shop.example.com comme élément supplémentaire.
• Ce contrôle s'applique à toutes les requêtes envoyées avec ce jeton. Il en va de même que vous appeliez un chemin CMA ou un chemin CDA.
• Une requête arrêtée par ce contrôle est refusée avec un HTTP 403. Le code renvoyé figure dans Erreurs ci-dessous.

Erreurs

Ce sont les codes que l'on rencontre lorsque l'on manipule un Space Access Token. Pour les codes communs à toutes les ressources, consultez Erreurs communes.

API

L'URL de base de tous les points de terminaison ci-dessous est https://cma.weegloo.com/v1, et un jeton Bearer authentifiant la CMA est requis dans l'en-tête Authorization. La modification et la modification partielle d'un Space Access Token ne nécessitent pas l'en-tête X-Weegloo-Version.

Documents associés

• SpaceRole : définit le rôle (portée de lecture et d'écriture) à lier à ce jeton.
• Delivery Access Token : jeton de diffusion en lecture seule exposé aux visiteurs (pour le client).
• Personal Access Token : jeton Weegloo User pour les serveurs et la CI, lié à l'ensemble d'un compte.
• Tarifs : limite d'émission du Space Access Token par formule.