Space Access Token

El Space Access Token es un token que puede leer y escribir contenido dentro de un único Space. Permite crear, modificar y eliminar contenido con CMA, y también se usa para llamar a la lectura de CDA y a Upload. Al emitirlo se vincula a un único SpaceRole, y ese rol define qué puede hacer el token y hasta dónde (con qué Content Type puede operar y con qué acciones).

A diferencia del Delivery Access Token, que es de solo lectura, este token llega a escribir. En cambio, a diferencia del Personal Access Token, que se liga a toda la cuenta de usuario, se limita a un único Space y no puede acceder a la configuración del Space, al plano de la organización y la cuenta, ni a otros Space. En CMA, el Space Access Token es un recurso secundario de Space, y su ruta se basa en /spaces/{spaceId}/space-access-tokens. Si este token se coloca en un servidor o en un cliente público (por ejemplo, escritura anónima) se decide según el servicio. Como es un token potente con permiso de escritura, la seguridad se consigue acotando el rol que se vincula al alcance de exposición del lugar donde se coloca el token (consulta Seguridad: vinculación del rol según el alcance de exposición más abajo).

Estructura del recurso

A continuación se muestra la respuesta al crear un Space Access Token. En sys (propiedades del sistema) se incluyen el valor del token y su alcance, y en el cuerpo están name y description.

{
  "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"]
  },
  "description": "Token de servidor para registrar y editar productos de la tienda de ropa",
  "name": "Servidor backend de productos"
}

Claves principales:

• sys.id: identificador único del Space Access Token. Se introduce en {spaceAccessTokenId} de las rutas de consulta, modificación y eliminación individuales.
• sys.space: Space al que pertenece este token. El token solo funciona en este único Space.
• sys.accessToken: valor del token secreto que se usa en las llamadas a la API. Empieza por SPCAT y, como aparece con el mismo valor incluso al consultarlo tras la emisión, hay que tener cuidado con su exposición (consulta la sección de seguridad más abajo).
• sys.scopes: alcance de permisos del token. El Space Access Token siempre es ["SPACE_ACCESS_TOKEN"] al emitirse.
• sys.user: usuario dedicado que es el sujeto de permisos de este token. Se crea automáticamente al emitirlo, y los permisos del SpaceRole vinculado se otorgan a este usuario. Es decir, los permisos efectivos del token provienen de este usuario. Es un usuario distinto de quien emitió realmente este token (sys.createdBy).
• name: nombre del token indicado al crearlo (por ejemplo, Servidor backend de productos).
• description: descripción del token (opcional).

El role (el SpaceRole a vincular) es un valor de entrada que solo se envía en el cuerpo de la petición de creación, y no se incluye en el recurso de respuesta. Como el rol vinculado se concede al usuario propio de este token (el sys.user de la respuesta), no vuelve en la respuesta de consulta como campo role. El accessToken del ejemplo anterior es un valor secreto, por eso se ha sustituido por una cadena de ejemplo. En realidad es una cadena larga y opaca que empieza por SPCAT, y aparece con el mismo valor aunque se vuelva a consultar tras la emisión.

Propiedades del sistema (sys)

Todo Space Access Token incluye en el objeto sys las propiedades de sistema comunes y las propiedades propias del token. space, user, createdBy y updatedBy se incluyen con forma Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Propiedades del cuerpo:

Entrada exclusiva del cuerpo de la petición de creación:

Seguridad: vinculación del rol según el alcance de exposición

El Space Access Token es un token potente que llega a escribir. El SpaceRole al que se vincule constituye el límite de lo que este token puede hacer y, a la vez, su límite de seguridad. Si este token se coloca en un servidor o en un cliente público (por ejemplo, escritura anónima) se decide según el servicio, y la seguridad no se consigue por "dónde se esconde", sino acotando el rol vinculado al alcance de exposición.

• En el role de la petición de creación introduce el sys.id de un SpaceRole acotado que solo permita las acciones necesarias para ese uso. Vincula lo mínimo según el alcance de exposición: para un token de servidor de registro de productos, un rol que solo permita leer y escribir el Content Type de productos; para un token público de escritura anónima, un rol que solo permita crear (create) sobre el Content Type de publicaciones.
• Cuanto más se expone un token en un cliente público, más acotado se elige el rol. Solo debe permitir hasta el alcance que puedas asumir aunque el token se filtre. No vincules el rol Administrator ni un rol de escritura amplio a un token público. Además, no uses sin querer el primer elemento de la lista de SpaceRole; especifica de forma explícita el sys.id del rol acotado que pretendes.
• Para la entrega de solo lectura expuesta a los visitantes es más adecuado el Delivery Access Token, que no tiene permiso de escritura. Usa el Space Access Token solo cuando necesites escribir, y acota su rol según el alcance de exposición.
• El accessToken es un valor secreto que se consulta con el mismo valor incluso después de la emisión. Donde no haga falta exponerlo, no lo dejes en texto plano en el código, los registros, el almacenamiento ni los mensajes de error; y si sospechas que se ha filtrado, elimínalo para invalidarlo y sustitúyelo por un token nuevo.

(Fuente: skills weegloo-space-access-token y weegloo-delivery-access-token, .claude/rules/weegloo-global-rules.md.)

Estado y restricciones

Restricciones de valor que se respetan al crear y modificar.

Reglas sobre la vinculación y los permisos:

• El role a vincular debe existir realmente en ese Space. Si introduces el sys.id de un rol que no existe, la creación se rechaza (WGL404001). Un spaceId incorrecto también falla con el mismo código.
• El llamante solo puede vincular los roles que él mismo tiene en ese Space. Es una restricción para impedir que se conceda al token un permiso mayor vinculando un rol que el llamante no posee; si se infringe, se rechaza con WGL422001. No obstante, el administrador de ese Space (quien tiene el rol Administrator) no está sujeto a esta restricción y puede vincular cualquier rol.
• El Space Access Token es un recurso con límite de cantidad. Si superas el límite de emisiones de tu plan actual, la creación se rechaza (WGL429001). Consulta el límite por plan en Planes de precios.
• La emisión y la gestión (crear, consultar, modificar, eliminar) requieren el permiso de configuración de API Key de ese Space. Un Space Access Token no puede crear por sí mismo otro Space Access Token.

API

La URL base de todos los endpoints siguientes es https://cma.weegloo.com/v1, y se requiere un token Bearer que autentique en CMA en la cabecera Authorization. La modificación y la modificación parcial del Space Access Token no requieren la cabecera X-Weegloo-Version.

Documentos relacionados

• SpaceRole: define el rol (alcance de lectura y escritura) que se vincula a este token.
• Delivery Access Token: token de entrega de solo lectura expuesto a los visitantes (para el cliente).
• Personal Access Token: token de Weegloo User para servidores y CI, ligado a toda la cuenta.
• Planes de precios: límite de emisión de Space Access Token por plan.