Delivery Access Token

O DeliveryAccessToken é um token de leitura usado para ler conteúdo publicado a partir da CDA (entrega pública). Quando o navegador de um site ou aplicativo busca conteúdo publicado, ele chama a CDA com esse token. No momento da emissão, o token é vinculado a um único SpaceRole, e esse papel define o escopo de leitura do token (quais Content Type podem ser lidos).

Na CMA, o DeliveryAccessToken é um recurso subordinado ao Space, e seu caminho tem como base /spaces/{spaceId}/delivery-access-tokens. Como esse token opera exposto ao navegador (cliente), o papel vinculado deve ser definido com o menor privilégio possível (least-privilege), lendo apenas os Content Type necessários (consulte Segurança: vínculo de menor privilégio abaixo). Além disso, se você colocar em allowedReferrers as origens a partir das quais a chamada é permitida, este token não pode ser usado fora dos sites indicados (consulte Regras de formato da origem e Verificação do Referer).

Estrutura do recurso

A seguir está a resposta obtida ao criar um DeliveryAccessToken. O sys (propriedades do sistema) contém o valor e o escopo do token, e o corpo contém name, description e 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 somente leitura para o site público da loja de roupas",
  "name": "Entrega pública do site"
}

Chaves principais:

• sys.id: identificador único do DeliveryAccessToken. Entra em {deliveryAccessTokenId} nos caminhos de consulta, atualização e exclusão individuais.
• sys.accessToken: valor secreto do token usado nas chamadas à CDA. Como o mesmo valor aparece também nas consultas após a emissão, é preciso ter cuidado com a exposição (consulte a seção de segurança abaixo).
• sys.scopes: escopo de permissões do token. O DeliveryAccessToken é sempre ["DELIVERY_ACCESS_TOKEN"] no momento da emissão.
• sys.user: o usuário dedicado que é o sujeito de permissões deste token. É criado automaticamente na emissão, e as permissões do SpaceRole vinculado são concedidas a esse usuário. Ou seja, as permissões efetivas do token vêm desse usuário. É um usuário diferente de quem realmente emitiu este token (sys.createdBy).
• name: nome do token definido na criação (por exemplo, Entrega pública do site).
• description: descrição do token (opcional).
• allowedReferrers: lista que restringe de quais origens este token pode ser chamado. Se a lista estiver vazia, não há restrição. O token do exemplo acima só passa quando a chamada vem do site público da loja de roupas (https://shop.example.com) (para as regras de formato e a forma de verificação, consulte Regras de formato da origem e Verificação do Referer).

O accessToken do exemplo acima foi substituído por uma string de exemplo por ser um valor secreto. Na prática é uma string longa e opaca, e o mesmo valor aparece mesmo quando o token é consultado novamente após a emissão.

Propriedades do sistema (sys)

Todo DeliveryAccessToken mantém as propriedades comuns do sistema e as propriedades próprias do token no objeto sys. space, user, createdBy e updatedBy entram no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Propriedades do corpo:

Segurança: vínculo de menor privilégio

O DeliveryAccessToken é um token que chama a CDA exposto ao navegador e aos visitantes. Por isso, o SpaceRole ao qual ele é vinculado se torna o limite de segurança deste token.

• No campo role da requisição de criação, coloque o sys.id de um SpaceRole de menor privilégio que leia apenas os Content Type necessários. Para a entrega pública, recomenda-se um papel somente de leitura.
• Nunca vincule o papel Administrator. Como este token é exposto ao cliente, vincular um papel com permissões administrativas faz com que essas permissões vazem diretamente para fora. Além disso, não use por descuido o primeiro item da lista de SpaceRole; especifique explicitamente o sys.id do papel de menor privilégio pretendido.
• Delimite também com allowedReferrers os lugares onde este token pode ser usado. O papel vinculado define o que se pode ler com este token, e esta lista define de onde ele pode ser chamado. Um token que funciona no navegador não consegue esconder o próprio valor; assim, se você colocar na lista a origem do site público, mesmo que o valor do token vaze para fora, as chamadas à CDA feitas fora desse site não passam (consulte Verificação do Referer).
• O accessToken é um valor secreto que continua sendo consultado com o mesmo valor após a emissão. Injete-o com segurança no build do cliente, mas não o exponha diretamente para fora.

Status e restrições

Restrições de valor a respeitar na criação e na atualização.

Regras sobre vínculo e permissões:

• O role a vincular precisa realmente existir naquele Space. Se você colocar o sys.id de um papel que não existe naquele Space, a criação é recusada.
• O chamador só pode vincular os papéis que ele mesmo possui naquele Space. É uma restrição para impedir que se conceda ao token uma permissão mais alta vinculando um papel que o chamador não tem, e uma requisição de criação que a viole é recusada. Porém, o administrador daquele Space (quem possui o papel Administrator) não está sujeito a essa restrição e pode vincular qualquer papel.
• O DeliveryAccessToken é um recurso com limite de quantidade. Se você ultrapassar o limite de emissões do plano atual, a criação é recusada. Consulte os limites por plano em Planos.
• A emissão e o gerenciamento (criar, consultar, atualizar, excluir) exigem que o settings do papel do chamador contenha SETTING_DELIVERY_ACCESS_TOKEN. Como é uma ação separada de SETTING_SPACE_ACCESS_TOKEN, que emite o Space Access Token com permissão de escrita, é possível conceder apenas a permissão de emitir o token de entrega e bloquear a emissão do token de escrita (consulte SpaceRole).
• Esta API é chamada apenas com a sessão de login do console e com o Personal Access Token. Um DeliveryAccessToken emitido não pode, por si mesmo, criar outro DeliveryAccessToken.

Regras de formato da origem

Cada item de allowedReferrers é uma string que aponta para uma origem a partir da qual a chamada é permitida. Escreva no formato a seguir.

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

A lista aceita no máximo 50 itens, e a mesma origem não pode ser incluída duas vezes. As regras que cada item precisa seguir são estas.

• Use apenas o esquema https. O http é permitido somente em localhost, 127.0.0.1 e [::1].
• Use o curinga apenas como um único rótulo *. no início. Ele não pode ser usado no caminho.
• Escreva o host em ASCII. Coloque os domínios internacionalizados na notação Punycode.
• A porta vai de 1 a 65535. Se você omitir a porta, vale a porta padrão do esquema (443 para https e 80 para http).
• Se você escrever um caminho, a requisição só passa quando o caminho dela é exatamente igual. Como o navegador envia o caminho com codificação por porcentagem, escreva apenas ASCII no caminho.
• Itens que trazem informação de usuário (user@), consulta (?) ou fragmento (#) são recusados.

Essa verificação vale nos três caminhos: criação, atualização completa e atualização parcial. Se houver um único item que viole as regras, a lista não é salva e a requisição é recusada, e um dos itens que violaram as regras é informado no motivo do erro (consulte Erros).

Verificação do Referer

Depois da emissão, quando você chama a CDA com este token, o allowedReferrers é aplicado a cada requisição para decidir se ela passa.

• Se a lista estiver vazia, não há restrição. A chamada passa a partir de qualquer origem.
• Se a lista tiver ao menos um item, a verificação usa o valor do cabeçalho Referer da requisição. O cabeçalho Origin não é consultado.
• Se o cabeçalho Referer estiver ausente ou com o valor vazio, a requisição é recusada. O navegador envia esse cabeçalho por conta própria, mas, para um token que vai ser usado onde o Referer não é enviado, como em um script de build executado no servidor ou na renderização no servidor, deixe a lista vazia.
• Para passar, o esquema, o host e a porta do Referer precisam ser todos iguais aos de um item da lista. Se esse item tiver um caminho, o caminho também precisa ser igual.
• O item https://*.shop.example.com abrange todos os hosts que terminam em .shop.example.com, como admin.shop.example.com, e não abrange o próprio shop.example.com. Para permitir os dois, inclua também https://shop.example.com como um item à parte.
• Essa verificação vale para todas as requisições enviadas com este token. É igual para qualquer caminho da CDA que você chame.
• A requisição barrada na verificação é recusada com HTTP 403. O código devolvido está em Erros abaixo.

Erros

São os códigos que você encontra ao lidar com o DeliveryAccessToken. Para os códigos comuns a todos os recursos, consulte Erros comuns.

API

A URL base de todos os endpoints abaixo é https://cma.weegloo.com/v1, e o cabeçalho Authorization precisa de um token Bearer que autentique na CMA. A atualização e a atualização parcial do DeliveryAccessToken não exigem o cabeçalho X-Weegloo-Version.

Documentos relacionados

• SpaceRole: define o papel (escopo de leitura) a vincular a este token.
• Visão geral da CDA: a API de entrega que lê o conteúdo publicado com este token.
• Space Access Token: token que também escreve dentro de um único Space (tem a mesma restrição de origem).
• Personal Access Token: token de Weegloo User para servidor e CI.