SpaceRole

SpaceRole é um conjunto de permissões concedido aos membros de um Space. Reúne em um único recurso o que se pode fazer (ler, criar, editar, excluir, publicar) sobre Content Type, Content e Media, se é possível executar e gerenciar Script, e se há acesso às configurações do Space. Os filtros que estreitam o escopo das permissões (apenas determinado Content Type, apenas o que o próprio usuário criou, e assim por diante) também são definidos dentro do SpaceRole.

Um SpaceRole criado, por si só, não se aplica a ninguém. Você o concede a um membro inserindo o Refer deste SpaceRole em roles do Space Membership. Um mesmo membro pode ter vários SpaceRole ao mesmo tempo. Além disso, um DeliveryAccessToken também é vinculado a um único SpaceRole de least-privilege (privilégio mínimo), o que determina o escopo que pode ser entregue por esse token.

Estrutura do recurso

A seguir está a resposta da consulta individual do SpaceRole "Produto somente leitura". Junto com sys (propriedades do sistema), ele tem as propriedades de corpo que definem as permissões: contentType, content, media, settings e script.

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7ObyNrQQbHbm",
    "type": "SpaceRole",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-16T09:53:16.617Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-16T09:53:16.617Z",
    "isLocked": false,
    "version": 1
  },
  "name": "Produto somente leitura",
  "contentType": { "All": { "Allow": [] } },
  "content": {
    "Read": {
      "Allow": [
        { "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } } }
      ]
    }
  },
  "media": { "All": { "Allow": [] } },
  "settings": [],
  "script": {}
}

Chaves principais:

• contentType: mapa de permissões sobre o Content Type em si (o esquema). Define, por ação, a permissão de ler, criar, alterar, excluir e publicar o Content Type.
• content: mapa de permissões sobre o Content (os dados de conteúdo). O exemplo acima limita a leitura apenas ao Content de um determinado Content Type.
• media: mapa de permissões sobre a Media (arquivos e imagens).
• script: mapa de permissões sobre o Script (endpoints de backend declarativos que o seu frontend chama). Define, por ação, a execução (Execute) e o gerenciamento (criar, ler, editar, excluir).
• settings: array de strings que define a permissão de acesso às configurações do Space. Não é um mapa de permissões: lista diretamente os nomes das ações. Acesso total é ["SETTING_ALL"], para não conceder acesso a nenhuma configuração use [], e também é possível escolher apenas as configurações necessárias (consulte settings abaixo).
• isLocked: se for true, trata-se de um papel fornecido por padrão pelo Weegloo (por exemplo, Administrator), que não pode ser modificado nem excluído.

Propriedades do sistema (sys)

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

SpaceRole é um recurso de configuração sem o conceito de publicação. Por isso, ao contrário de Content e Media, ele não tem publish, archive ou status em sys, tendo apenas version. O version aumenta a cada modificação do SpaceRole.

Mapa de permissões: contentType, content, media

contentType, content e media são, cada um, um mapa que tem ações como chaves. As ações que podem ser usadas são Create (criar), Read (ler), Edit (editar), Delete (excluir), Publish (publicar), Unpublish (cancelar publicação), Archive (arquivar) e Unarchive (desarquivar), havendo também All, que indica todas as ações de uma vez. Não existe uma ação chamada Save. A permissão de modificação é Edit, e Save é o nome de um evento assinado pelo Webhook. O valor de cada ação é um objeto que contém os arrays de regras Allow (permitir) e Deny (negar).

"content": {
  "Read":   { "Allow": [ /* regra */ ], "Deny": [ /* regra */ ] },
  "Edit":   { "Allow": [ /* regra */ ] }
}

Cada objeto de regra (rule) tem filtros opcionais que estreitam o escopo da permissão.

• self: limita o alvo ao qual a regra se aplica ao próprio recurso, apenas ele. Insere-se um Refer que aponta para o recurso alvo. No mapa contentType significa um único Content Type; no mapa script, um único Script.
• contentType: limita ao Content Type ao qual aquele Content pertence. Insere-se um Refer que aponta para o Content Type.
• createdBy: limita apenas aos recursos criados por um determinado usuário. Se você inserir o id de um usuário específico em sys.id, limita apenas ao que essa pessoa criou; se inserir o valor reservado :self, limita "apenas ao que o usuário que está chamando agora criou".
• tag: limita apenas aos recursos com uma determinada Tag.

Qual filtro tem sentido em qual mapa de permissões é algo definido. Se você inserir um filtro que não corresponde, o salvamento do papel é recusado. É porque, se ele fosse ignorado em silêncio, a regra que você julgou ter estreitado se tornaria uma permissão total.

• No mapa contentType, o alvo é indicado com self, e não com contentType. É porque se trata de limitar o próprio Content Type. O filtro contentType significa "o tipo que este recurso referencia", portanto só cabe no mapa content.
• Um filtro que tenta estreitar por um eixo que aquele recurso não tem (tag em um Content Type, contentType em um Media) não tem o salvamento bloqueado, mas a regra não é avaliada como se pretendia. Não os use.

Ao avaliar o filtro createdBy (incluindo :self) na CDA (entrega), o publishWithAuthor do Content Type alvo precisa ser true. A CDA avalia esse filtro pelo sys.createdBy do snapshot publicado; se o publishWithAuthor estiver no valor padrão false, o snapshot não tem autor, então a regra Allow não corresponde a nada e a regra Deny não filtra ninguém. A CMA (gerenciamento) avalia pelo sys.createdBy do rascunho, portanto independe dessa configuração. Como o publishWithAuthor não é retroativo, ele precisa ser ativado antes de publicar o conteúdo, e o Content já publicado precisa ser publicado novamente. Consulte a explicação de publishWithAuthor em Content Type.

Um array Allow vazio [] significa permitir a ação sobre todo o tipo correspondente. Como o filtro está vazio, não há nada a filtrar, então a ação fica aberta para todos os recursos.

Um array Deny vazio [] funciona ao contrário. Não significa "não negar nada", e sim negar todo o tipo correspondente, bloqueando aquela ação por completo. Ela fica bloqueada mesmo que você escreva um Allow junto. Deixar [] com o sentido de que não há nada a negar produz o efeito exatamente oposto, portanto, para não negar nada, não inclua a própria chave Deny.

Exemplo 1: Administrator (permissões totais, fornecido por padrão)

O papel Administrator concede Allow vazio na ação All em contentType, content, media e script, permitindo tudo, e atribui ["SETTING_ALL"] a settings, acessando todas as configurações do Space. Como esse papel é fornecido por padrão pelo Weegloo, seu sys.isLocked é true e ele não pode ser modificado nem excluído.

{
  "sys": {
    "id": "3trmXRLdJF4GBlAjtcuoWfVubsasp4",
    "type": "SpaceRole",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "_", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-14T14:56:04.737Z",
    "updatedBy": { "sys": { "id": "_", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-14T14:56:04.737Z",
    "isLocked": true,
    "version": 1
  },
  "name": "Administrator",
  "description": "Members of this role have full access to everything in this space.",
  "contentType": { "All": { "Allow": [] } },
  "content": { "All": { "Allow": [] } },
  "media": { "All": { "Allow": [] } },
  "settings": ["SETTING_ALL"],
  "script": { "All": { "Allow": [] } }
}

Exemplo 2: Somente leitura (apenas um Content Type)

Este é um exemplo de papel de least-privilege que você cria por conta própria. Coloca-se uma regra apenas na ação Read de content e, pelo filtro contentType dessa regra, limita-se a um único Content Type. O próprio Content Type e a Media foram deixados abertos com All em Allow vazio, mas os dados de conteúdo só podem ser lidos para aquele único tipo. Como settings é [], não há acesso às configurações do Space. Quando se vincula esse tipo de papel a um DeliveryAccessToken, o token de entrega passa a ler apenas aquele escopo. O JSON deste papel é igual ao "Produto somente leitura" em Estrutura do recurso acima.

settings (acesso às configurações do Space)

settings não é um mapa de permissões, mas um array de strings. Contém a permissão de acesso às configurações do Space e não tem Allow/Deny nem filtros. As ações que você coloca no array são permitidas; as que você deixa de fora não são.

Acesso total é ["SETTING_ALL"]; para não conceder nenhum acesso, deixa-se []. Se você precisa de algo entre os dois, escolha as ações abaixo.

Os dois tipos de token têm ações separadas. Se você conceder apenas SETTING_DELIVERY_ACCESS_TOKEN, é possível emitir o Delivery Access Token somente leitura, mas não o Space Access Token, que também permite escrita.

As ações de settings são chamadas apenas com uma sessão de login do console e com um Personal Access Token. Um Space Access Token, um Delivery Access Token ou um token de ServiceUser não consegue chamar as APIs desta lista, independentemente de quais ações estejam no papel.

A lista de ações dos mapas de permissões (contentType, content, media, script), as chaves de filtro (self, contentType, createdBy, tag), o significado de :self e também qual filtro é válido em qual mapa seguem a seção Mapa de permissões: contentType, content, media acima.

script (permissões de Script)

script é o mapa de permissões sobre o Script (endpoints de backend declarativos que o seu frontend chama). Sua estrutura é igual à de content e media: ações como chaves, com arrays de regras Allow/Deny como valores. As ações usadas são as seguintes:

• Create, Read, Edit, Delete: criar, consultar, alterar e excluir o recurso Script.
• Execute: executa o Script (chamada de /execute). É uma ação exclusiva do Script.
• All: a ação abrangente que inclui todas as anteriores.

Como o Script não é um recurso que se publica, ações de publicação como Publish/Unpublish não são usadas. Como filtros de regra é possível usar dois: self e createdBy.

• self: limita a um único Script. Insere-se um Refer que aponta para aquele Script (com targetType igual a Script).
• createdBy: limita por quem o criou (com :self, "apenas os Script que o próprio usuário criou").

contentType e tag não são eixos que se vinculem ao Script, portanto inseri-los faz o salvamento do papel ser recusado.

Por exemplo, para permitir a execução de qualquer Script, mas restringir a consulta apenas ao que o próprio usuário criou, escreve-se assim:

"script": {
  "Execute": { "Allow": [] },
  "Read": {
    "Allow": [
      { "createdBy": { "sys": { "id": ":self", "type": "Refer", "targetType": "User" } } }
    ]
  }
}

Estreitar com self resulta na permissão mínima, capaz de executar um único Script. Ao dar permissão de execução a um sistema externo, como uma processadora de pagamentos, é a forma de abrir apenas o único canal que esse sistema vai chamar e deixar o resto fechado.

"script": {
  "Execute": {
    "Allow": [
      { "self": { "sys": { "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK", "type": "Refer", "targetType": "Script" } } }
    ]
  }
}

Se você vincular este papel a um Space Access Token, aquele token executa apenas o único Script indicado. O motivo de estreitar até uma única permissão de execução e o fato de a execução de um Script receber as permissões delegadas do autor são abordados em Semântica de execução, restrições e segurança do Script.

Essa permissão script define "se é possível executar e gerenciar o recurso Script". À parte disso, ao elaborar um Script (criá-lo ou alterá-lo), no momento de salvar o autor precisa realmente ter as permissões de ação sobre Content e Media que os statements desse Script manipulam; caso contrário, o salvamento é recusado (veja Erros do Script). Mais detalhes em Semântica de execução, restrições e segurança do Script.

Erros

São os códigos que você encontra ao lidar com o SpaceRole. 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 é necessário um token Bearer que autentique no CMA no header Authorization. A modificação de papéis (PUT, PATCH) exige enviar também o header X-Weegloo-Version (o sys.version do recurso atual) para o controle de concorrência otimista. A criação e a exclusão não têm esse header. Papéis fornecidos por padrão com sys.isLocked igual a true não podem ser modificados nem excluídos.

Documentos relacionados

• Space Membership: vincular o SpaceRole a roles do membro.
• Delivery Access Token: token de entrega vinculado a um SpaceRole de least-privilege.
• Content Type: o Content Type que as regras de permissão apontam.