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, o plano 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 e 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 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).

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.
• 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.

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

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 (WGL404001). Um spaceId incorreto também falha com o mesmo código.
• 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; violá-la resulta em recusa com WGL422001. 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 (WGL429001). Consulte os limites por plano em Planos.
• A emissão e o gerenciamento (criar, consultar, atualizar, excluir) exigem a permissão de configuração de API Keys daquele Space. Um Space Access Token não pode, por si mesmo, criar outro Space Access Token.

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.