Delivery Access Token

El DeliveryAccessToken es un token de solo lectura que se usa para leer contenido publicado desde CDA (entrega pública). El navegador de un sitio web o una aplicación llama a CDA con este token al obtener el contenido publicado. Al emitirlo, se vincula a un único SpaceRole, y ese rol define el alcance de lectura del token (qué Content Type puede leer).

En CMA, el DeliveryAccessToken es un recurso secundario de Space, y su ruta se basa en /spaces/{spaceId}/delivery-access-tokens. Como este token opera expuesto en el navegador (cliente), el rol al que se vincule debe definirse con el privilegio mínimo (least-privilege), de modo que solo lea los Content Type necesarios (consulta Seguridad: vinculación con privilegio mínimo más abajo). Además, si en allowedReferrers incluyes los orígenes desde los que se permite la llamada, este token no se puede usar fuera de los sitios indicados (consulta Reglas de notación del origen y Comprobación del Referer).

Estructura del recurso

A continuación se muestra la respuesta al crear un DeliveryAccessToken. 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": "3trmXRM3RqbgSnifyg7PUFQuOAqWOc",
    "type": "DeliveryAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQw6hf9kGj", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T09:24:23.156Z",
    "updatedBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T09:24:23.156Z",
    "accessToken": "DVRATbQ8mX2vK9pLs7Rf1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["DELIVERY_ACCESS_TOKEN"]
  },
  "allowedReferrers": ["https://shop.example.com"],
  "description": "Token de entrega de solo lectura para el sitio público de la tienda de ropa",
  "name": "Entrega pública del sitio web"
}

Claves principales:

• sys.id: identificador único del DeliveryAccessToken. Se introduce en {deliveryAccessTokenId} de las rutas de consulta, modificación y eliminación individuales.
• sys.accessToken: valor del token secreto que se usa en las llamadas a CDA. 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 DeliveryAccessToken siempre es ["DELIVERY_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, Entrega pública del sitio web).
• 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 el token solo pasa cuando la llamada viene del sitio público de la tienda de ropa (https://shop.example.com); para la notación y el modo de comprobación, consulta Reglas de notación del origen y Comprobación del Referer.

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, y aparece con el mismo valor aunque se vuelva a consultar después de la emisión.

Propiedades del sistema (sys)

Todo DeliveryAccessToken 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:

Seguridad: vinculación con privilegio mínimo

El DeliveryAccessToken es un token que llama a CDA expuesto al navegador y a los visitantes. Por eso, el SpaceRole al que se vincule constituye el límite de seguridad de este token.

• En el role de la petición de creación se introduce el sys.id del SpaceRole con privilegio mínimo que solo lee los Content Type necesarios. Para la entrega pública se recomienda un rol de solo lectura.
• No vincules nunca el rol Administrator. Como este token queda expuesto en el cliente, vincular un rol con permisos de administración filtraría esos permisos directamente al exterior. Además, no uses sin querer el primer elemento de la lista de SpaceRole; especifica de forma explícita el sys.id del rol con privilegio mínimo que pretendes.
• Acota con allowedReferrers también los lugares donde se puede usar este token. El rol vinculado define qué se puede leer con este token, y esta lista define desde dónde se puede llamar. En un token que funciona en el navegador no se puede ocultar el valor en sí, así que, si incluyes en la lista el origen del sitio público, las llamadas a CDA no pasan fuera de ese sitio aunque el valor del token se filtre (consulta Comprobación del Referer).
• El accessToken es un valor secreto que se consulta con el mismo valor incluso después de la emisión. Inyéctalo de forma segura en la compilación del cliente, pero no lo expongas tal cual al exterior.

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 en ese Space, 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 DeliveryAccessToken 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_DELIVERY_ACCESS_TOKEN. Es una acción independiente de SETTING_SPACE_ACCESS_TOKEN, que emite el Space Access Token (el que llega a escribir), así que se puede conceder solo el permiso de emisión del token de entrega y bloquear la emisión del token de escritura (consulta SpaceRole).
• Esta API solo se llama desde una sesión iniciada en la consola o con un Personal Access Token. Un DeliveryAccessToken ya emitido no puede crear otro DeliveryAccessToken.

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 CDA 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. El navegador envía esta cabecera por sí mismo. Aun así, deja la lista vacía en los tokens que vayas a usar donde no se envía Referer, como un script de compilación que corre en el servidor o el renderizado en el servidor.
• 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 de CDA que llames.
• 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 DeliveryAccessToken. 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 DeliveryAccessToken no requieren la cabecera X-Weegloo-Version.

Documentos relacionados

• SpaceRole: define el rol (alcance de lectura) que se vincula a este token.
• Resumen de CDA: la API de entrega que lee el contenido publicado con este token.
• Space Access Token: token que llega a escribir dentro de un único Space (tiene la misma restricción de origen).
• Personal Access Token: token de Weegloo User para servidores y CI.