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

# Role

> Papéis de acesso internos, de ambiente ou customizados por organização

## Campos

| Campo            | Tipo        | Descrição                                                       |
| ---------------- | ----------- | --------------------------------------------------------------- |
| `roleId`         | `UUID`      | Identificador único                                             |
| `organizationId` | `UUID?`     | Referência à organização; preenchido apenas para `ORGANIZATION` |
| `type`           | `RoleType`  | Tipo da role (`INTERNAL`, `ENVIRONMENT` ou `ORGANIZATION`)      |
| `name`           | `String`    | Nome do papel (ex.: "Admin", "Agente")                          |
| `description`    | `String?`   | Descrição do papel                                              |
| `createdBy`      | `UUID?`     | Usuário que criou o registro, quando aplicável                  |
| `createdAt`      | `DateTime`  | Data de criação                                                 |
| `updatedBy`      | `UUID?`     | Usuário que fez a última atualização, quando aplicável          |
| `updatedAt`      | `DateTime`  | Data da última atualização                                      |
| `deletedBy`      | `UUID?`     | Usuário que removeu o registro, quando aplicável                |
| `deletedAt`      | `DateTime?` | Data de remoção                                                 |

## Relacionamentos

* Relaciona-se com [Organization](/data-modelling/tenant/organization) (opcional)
* Relaciona-se com múltiplos [RolePermission](/data-modelling/authorization/role-permission)
* Relaciona-se com múltiplos [Membership](/data-modelling/tenant/membership)
* Relaciona-se com múltiplos [Invite](/data-modelling/tenant/invite)

## Regras de Negócio

* `INTERNAL` é usado apenas no BackOffice e não pertence a uma organização.
* `ENVIRONMENT` é uma role global reutilizável por organizações; a organização aparece na [Membership](/data-modelling/tenant/membership), não na Role.
* `ORGANIZATION` é customizada por uma organização e exige `organizationId` preenchido.
* Um papel é um conjunto nomeado de permissions do catálogo do DEVMOB.
* Usuários são associados a roles por [Membership](/data-modelling/tenant/membership).
* Exclusão é lógica (`deletedAt`); papéis excluídos são ignorados nas consultas.
* Ao criar uma organização, o owner recebe uma Membership `ACTIVE` com uma role admin de ambiente compatível com o tipo da organização.

## Enums

### RoleType

| Valor          | Descrição                                                  |
| -------------- | ---------------------------------------------------------- |
| `INTERNAL`     | Role interna para BackOffice, fora de qualquer organização |
| `ENVIRONMENT`  | Role global reutilizável por organizações                  |
| `ORGANIZATION` | Role customizada por uma organização                       |

## Example

```json theme={null}
{
  "roleId": "0197a7f8-15d1-7320-9b60-02497d7a0d61",
  "organizationId": null,
  "type": "ENVIRONMENT",
  "name": "Agente de Vendas",
  "description": "Role padrão para operação de vendas em empresa",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-03T13:10:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-03T13:10:00.000Z",
  "deletedBy": null,
  "deletedAt": null
}
```