Space Access Token

O Space Access Token é um token que pode ler e escrever conteúdo dentro de um único Space. Com ele é possível criar, editar e excluir conteúdo pela CMA, e as leituras na CDA e o Upload também são chamados com esse token. No momento da emissão, ele é vinculado a um único SpaceRole, e esse papel define o que o token pode fazer e até onde (quais Content Type ele pode manipular e com quais ações).

Ao contrário do Delivery Access Token, que é somente de leitura, este token também escreve. Em compensação, ao contrário do Personal Access Token, que fica atrelado à conta inteira do usuário, ele se limita a um único Space e não acessa as configurações do Space, os âmbitos de organização e de conta, nem outros Space. Na CMA, o Space Access Token é um recurso subordinado ao Space, e seu caminho tem como base /spaces/{spaceId}/space-access-tokens. Colocar este token em um servidor ou em um cliente exposto (por exemplo, escrita anônima) é algo que você define conforme o serviço. Como é um token poderoso, com permissão de escrita, você garante a segurança restringindo o papel vinculado ao escopo de exposição do lugar onde o token fica (consulte Segurança: vínculo de papel ajustado ao escopo de exposição abaixo).

Estrutura do recurso

A seguir está a resposta obtida ao criar um Space Access Token. 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": "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 cadastro e edição de produtos da loja de roupas",
  "name": "Servidor de backend de produtos"
}

Chaves principais:

• sys.id: identificador único do Space Access Token. Entra em {spaceAccessTokenId} nos caminhos de consulta, atualização e exclusão individuais.
• sys.space: o Space ao qual este token pertence. O token só funciona neste único Space.
• sys.accessToken: valor secreto do token usado nas chamadas à API. Começa com SPCAT e, 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 Space Access Token é sempre ["SPACE_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, Servidor de backend de produtos).
• 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. No exemplo acima a lista ficou vazia porque é um token chamado a partir do servidor (para as regras de formato e a forma de verificação, consulte Regras de formato da origem e Verificação do Referer).

O role (o SpaceRole a vincular) é um valor de entrada enviado apenas no corpo da requisição de criação e não é incluído no recurso de resposta. O papel vinculado é concedido a um usuário dedicado a este token (o sys.user da resposta), por isso não retorna como campo role na resposta de consulta. 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 que começa com SPCAT, e o mesmo valor aparece mesmo quando o token é consultado novamente após a emissão.

Propriedades do sistema (sys)

Todo Space Access Token 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:

Entrada exclusiva do corpo da requisição de criação:

Segurança: vínculo de papel ajustado ao escopo de exposição

O Space Access Token é um token poderoso, que também escreve. A qual SpaceRole ele é vinculado é justamente o limite do que este token pode fazer e, ao mesmo tempo, o seu limite de segurança. Colocar este token em um servidor ou em um cliente exposto (por exemplo, escrita anônima) é algo que você define conforme o serviço; a segurança se garante não por "onde você o esconde", mas por restringir o papel vinculado ao escopo de exposição.

• No role da requisição de criação, coloque o sys.id de um SpaceRole restrito que permita apenas as ações necessárias para aquele uso. Se for um token de servidor para cadastro de produtos, vincule um papel que permita apenas ler e escrever o Content Type de produtos; se for um token público de escrita anônima, um papel que permita apenas a criação (create) sobre o Content Type de postagens. Vincule ao mínimo, conforme o escopo de exposição.
• Quanto mais um token fica exposto a um cliente público, mais restrito deve ser o papel. Só se deve permitir até o escopo que você consegue suportar caso o token vaze. Não vincule o papel Administrator nem papéis de escrita amplos a um token público. Além disso, não use por descuido o primeiro item da lista de SpaceRole; especifique explicitamente o sys.id do papel restrito pretendido.
• Se o token for chamado do navegador, restrinja também o ponto de chamada com allowedReferrers. O papel vinculado define o que se pode fazer com este token, e esta lista define de onde ele pode ser chamado (consulte Verificação do Referer).
• Para a entrega somente leitura exposta aos visitantes, o Delivery Access Token, que não tem permissão de escrita, é mais adequado. Use o Space Access Token apenas quando precisar escrever, e restrinja o seu papel ao escopo de exposição.
• O accessToken é um valor secreto que continua sendo consultado com o mesmo valor após a emissão. Onde não houver necessidade de expô-lo, não o deixe em texto simples em código, logs, armazenamento ou mensagens de erro; se suspeitar de exposição, invalide-o excluindo-o e substitua-o por um novo token.

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 inexistente, 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 Space Access Token é 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_SPACE_ACCESS_TOKEN. Como é uma ação separada de SETTING_DELIVERY_ACCESS_TOKEN, que emite o Delivery Access Token somente de leitura, é possível conceder apenas a permissão de emitir o token de entrega e bloquear a emissão deste token (consulte SpaceRole).
• Esta API é chamada apenas com a sessão de login do console e com o Personal Access Token. Um Space Access Token não pode, por si mesmo, criar outro Space Access Token, e isso vale mesmo que você coloque SETTING_SPACE_ACCESS_TOKEN no papel vinculado.

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 API 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. Para um token que vai ser usado onde o Referer não é enviado, como nas chamadas entre servidores, 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 chamado, na CMA ou na CDA.
• 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 Space Access Token. 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 Space Access Token não exigem o cabeçalho X-Weegloo-Version.

Documentos relacionados

• SpaceRole: define o papel (escopo de leitura e escrita) a vincular a este token.
• Delivery Access Token: token de entrega somente leitura exposto aos visitantes (para o cliente).
• Personal Access Token: token de Weegloo User para servidor e CI, atrelado à conta inteira.
• Planos: limite de emissões de Space Access Token por plano.