> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar papel

> Cria um papel personalizado. Exige `roles:manage`.

Exige `roles:manage`. Uma chave de API precisa do escopo `workspaces:write`.

> [!NOTE]
>
> **Guarda contra escalonamento de privilégio:** quem não é dono só pode conceder um conjunto de
> permissões que ele mesmo já tem. Não há verificação separada para "criar" e "editar" — sem isso,
> `roles:manage` sozinho permitiria que um membro criasse um papel com todas as permissões, inclusive
> as que ele não tem.

O número de papéis que um workspace pode ter é limitado pelo nível do plano do dono — **os 4 papéis
iniciais contam nesse limite.**

### Caminho

**id** `string` *required*

ID do workspace.

### Corpo

**name** `string` *required*

De 1 a 50 caracteres.

**permissions** `WorkspacePermission[]` *required*

Subconjunto do catálogo de 20 entradas. Deve ser um subconjunto das permissões do próprio chamador, a menos que o chamador seja o dono.

**position** `number`

De 0 a 999, ordem de exibição.

### Resposta

Mesmo formato de uma linha de [Listar papéis](https://docs.vertracloud.app/pt-br/api-reference/endpoint/workspaces/roles/list.md).

### Erros

| Status | Código | Quando |
| - | - | - |
| 403 | `WORKSPACE_PERMISSION_DENIED` | Quem chama não tem `roles:manage`. |
| 403 | `WORKSPACE_PERMISSION_ESCALATION` | Quem chama não é o dono e pediu uma permissão que não tem. |
| 404 | `WORKSPACE_NOT_FOUND` | O workspace não existe ou você não é membro. |
| 409 | `WORKSPACE_ROLE_LIMIT_REACHED` | Atingido o teto de papéis do nível de plano do dono (os papéis iniciais incluídos). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.