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. Que este token se coloque 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, description y 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": "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).
• allowedReferrers: lista que restringe desde qué orígenes se puede llamar a este token. Si la lista está vacía, no se aplica ninguna restricción. En el ejemplo anterior la lista se deja vacía porque el token se llama desde el servidor (para la notación y el modo de comprobación, consulta Reglas de notación del origen y Comprobación del Referer).

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. Que este token se coloque 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.
• Si el token se llama desde el navegador, acota también con allowedReferrers el punto desde el que se llama. El rol vinculado define qué se puede hacer con este token, y esta lista define desde dónde se puede llamar (consulta Comprobación del Referer).
• 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.

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.
• 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, y una petición de creación que la infrinja se rechaza. 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. Consulta el límite por plan en Planes de precios.
• La emisión y la gestión (crear, consultar, modificar, eliminar) requieren que el settings del rol del llamante incluya SETTING_SPACE_ACCESS_TOKEN. Es una acción independiente de SETTING_DELIVERY_ACCESS_TOKEN, que emite el Delivery Access Token de solo lectura, así que se puede conceder solo el permiso de emisión del token de entrega y bloquear la emisión de este token (consulta SpaceRole).
• Esta API solo se llama desde una sesión iniciada en la consola o con un Personal Access Token. Un Space Access Token no puede crear por sí mismo otro Space Access Token, y esto se cumple igual aunque en el rol vinculado se incluya SETTING_SPACE_ACCESS_TOKEN.

Reglas de notación del origen

Cada elemento de allowedReferrers es una cadena que señala un único origen desde el que se permite la llamada. Se escribe con esta forma.

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

La lista admite un máximo de 50 elementos, y el mismo origen no se puede incluir dos veces. Cada elemento debe cumplir estas reglas.

• El esquema solo puede ser https. El esquema http únicamente se permite en localhost, 127.0.0.1 y [::1].
• El comodín se usa solo como una etiqueta *. al principio. En la ruta no se puede usar.
• El host se escribe en ASCII. Los dominios internacionalizados se introducen en notación punycode.
• El puerto va de 1 a 65535. Si se omite, se toma el puerto predeterminado del esquema (443 para https y 80 para http).
• Si escribes una ruta, la petición solo pasa cuando su ruta es exactamente igual. Como el navegador envía la ruta con codificación porcentual, en la ruta solo se usa ASCII.
• Los elementos que llevan información de usuario (user@), consulta (?) o fragmento (#) se rechazan.

Esta comprobación se aplica en las tres rutas: creación, modificación completa y modificación parcial. Si hay al menos un elemento que incumple las reglas, la lista no se guarda y la petición se rechaza; el motivo del error indica uno de los elementos que incumplen (consulta Errores).

Comprobación del Referer

Cuando llamas a la API con este token después de emitirlo, en cada petición se aplica allowedReferrers para decidir si pasa.

• Si la lista está vacía, no se aplica ninguna restricción. La petición pasa desde cualquier origen.
• Si la lista tiene al menos un elemento, la decisión se toma con el valor de la cabecera Referer de la petición. La cabecera Origin no se consulta.
• Si la cabecera Referer falta o su valor está vacío, la petición se rechaza. Deja la lista vacía en los tokens que vayas a usar donde no se envía Referer, como en las llamadas entre servidores.
• Para que la petición pase, el esquema, el host y el puerto del Referer deben coincidir todos con un elemento de la lista. Si ese elemento lleva una ruta, la ruta también debe coincidir.
• https://*.shop.example.com incluye todos los hosts que terminan en .shop.example.com, como admin.shop.example.com, pero no incluye shop.example.com en sí. Para permitir ambos, añade https://shop.example.com como un elemento más.
• Esta comprobación se aplica a todas las peticiones que se envían con este token. Es igual sea cual sea la ruta que llames, tanto en CMA como en CDA.
• Las peticiones que no superan la comprobación se rechazan con un HTTP 403. El código que se devuelve está en Errores, más abajo.

Errores

Códigos que se encuentran al trabajar con Space Access Token. Para los códigos comunes a todos los recursos, consulta Errores comunes.

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.