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

# RBAC e Permissões

> Controle de acesso baseado em função e gerenciamento de permissões.

Truthlocks implementa controle de acesso baseado em função (RBAC) para gerenciar quem pode realizar quais ações. Este guia explica o modelo de permissões.

## Modelo de Permissão

O modelo de permissão Truthlocks consiste em três camadas:

**1. Permissões**

Ações atômicas como `attestations:mint` ou `users:read`. Estas são as
blocos de construção.

**2. Funções**

Coleções de permissões agrupadas por função. Funções como `admin`,
`issuer`, ou `viewer`.

**3. Atribuições**

Vinculando usuários ou chaves de API a funções. Um usuário pode ter várias funções.

## Permissões Disponíveis

### Permissões de Atestado

| Permissão | Descrição |
| - | - |
| `attestations:mint` | Criar novas atestações |
| `attestations:read` | Visualizar detalhes da atestação e baixar pacotes de prova |
| `attestations:revoke` | Revogar atestados existentes |
| `attestations:*` | Todas as permissões de atestação |

### Permissões do emissor

| Permissão | Descrição |
| - | - |
| `issuers:read` | Visualizar informações e chaves do emissor |
| `issuers:write` | Criar emissores, registar chaves |
| `issuers:*` | Todas as permissões do emissor |

### Permissões de Gerenciamento de Usuários

| Permissão | Descrição |
| - | - |
| `users:read` | Visualizar usuários e atribuições de função |
| `users:write` | Convidar usuários, atribuir funções, remover usuários |
| `api-keys:read` | Visualizar chaves de API (sem segredos) |
| `api-keys:write` | Criar e revogar chaves de API |

### Permissões Administrativas

| Permissão | Descrição |
| - | - |
| `audit:read` | Consultar logs de auditoria |
| `governance:approve` | Aprovar solicitações de governança |
| `governance:suspend` | Suspender emissores ativos |
| `*` | Superadministrador: todas as permissões |

### Permissões de webhook

| Permissão | Descrição |
| - | - |
| `webhooks:read` | Visualizar endpoints de webhook e logs de entrega |
| `webhooks:write` | Criar, atualizar e excluir endpoints |
| `webhooks:*` | Todas as permissões de webhook |

### Permissões de governação

| Permissão | Descrição |
| - | - |
| `governance:read` | Visualizar solicitações de governança |
| `governance:approve` | Aprovar solicitações de governança |
| `governance:suspend` | Suspender emissores ativos |
| `governance:*` | Todas as permissões de governança |

### Permissões de configurações

| Permissão | Descrição |
| - | - |
| `settings:read` | Visualizar configurações de locatário e organização |
| `settings:write` | Atualizar marca, domínios, e-mail e outras configurações |
| `settings:*` | Todas as permissões de configurações |

## Funções do sistema

Truthlocks provisiona um conjunto de funções do sistema automaticamente quando seu inquilino é criado. As funções do sistema não podem ser editadas ou excluídas.

| Função | Descrição | Permissões chave |
| :- | :- | :- |
| **Administrador de Inquilino** | Acesso total a todos os recursos dentro do inquilino | `*` (superadministrador) |
| **Administrador da Org** | Gerenciar emissores, usuários e atestados de uma única organização | `issuers:*`, `attestations:*`, `users:*`, `audit:read` |
| **Administrador do Emissor** | Gerenciar emissores e cunhar atestados | `issuers:*`, `attestations:*` |
| **Auditor** | Acesso somente leitura para monitoramento e conformidade | `attestations:read`, `issuers:read`, `audit:read` |

Você pode visualizar as funções do sistema na página **Funções** no console. Cada função mostra seu nome, descrição e um selo **Sistema**.

## Funções personalizadas

Crie funções personalizadas para definir permissões de acesso adaptadas à estrutura da sua equipe. As funções personalizadas estão disponíveis em todos os planos.

### Criando uma função personalizada no console

**1. Abrir a página de Funções**

Navegue até **Funções** na barra lateral da console.

**2. Clique em Criar Função Personalizada**

O botão **Criar Função Personalizada** abre uma caixa de diálogo onde você fornece:

* **Nome da Função** — um nome descritivo para a função (por exemplo, `Developer` ou `Compliance Officer`).
* **Descrição** — uma breve explicação para que serve a função.

**3. Salvar a função**

Clique em **Criar Função** para salvar. A nova função aparece na seção **Funções Personalizadas** da página Funções.

### Criando uma função personalizada via API

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/roles \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "attestation_minter",
    "description": "Can only mint attestations for specific issuers",
    "permissions": ["attestations:mint", "attestations:read", "issuers:read"],
    "constraints": {
      "issuer_ids": ["issuer-uuid-1", "issuer-uuid-2"]
    }
  }'
```

### Restrições em nível de recurso

Funções personalizadas suportam restrições opcionais que limitam as permissões a recursos específicos:

```json theme={null}
{
  "name": "regional_auditor",
  "description": "Audit access scoped to EU issuers only",
  "permissions": ["attestations:read", "issuers:read", "audit:read"],
  "constraints": {
    "issuer_ids": ["eu-issuer-uuid-1", "eu-issuer-uuid-2"]
  }
}
```

> [!NOTE]
>
> Restrições em nível de recurso (como limitação a emissores específicos) são
> disponível em planos Enterprise.

## Escopos de Chave de API vs. Funções de Usuário

Tanto as chaves de API quanto os usuários têm permissões, mas funcionam de forma diferente:

| Aspecto | Escopos da Chave API | Funções do Usuário |
| - | - | - |
| Atribuição | Definida na criação da chave, imutável | Pode ser alterada a qualquer momento |
| Trilha de Auditoria | Ações registradas como ID da chave API | Ações registradas como e-mail do usuário |
| Múltiplos | Uma chave = um conjunto de escopos | O usuário pode ter múltiplos papéis |
| Caso de Uso | Integração servidor-servidor | Usuários humanos via UI/painel |

## Melhores Práticas

* **Privilégio Mínimo:** Conceda apenas as permissões necessárias para cada função
* **Separação de Deveres:** Não atribua a uma única função tanto `attestations:mint` quanto `governance:approve`
* **Auditorias Regulares:** Revise as atribuições de função trimestralmente
* **Use Chaves de API para Automação:** Não compartilhe credenciais de usuário para scripts
* **Documentar Funções Personalizadas:** Mantenha um registro do motivo pelo qual as funções personalizadas foram criadas

## Próximos passos

> [card] [Registros de Auditoria](https://docs.truthlocks.com/security/audit.md)
>
> Rastreie todos os eventos relacionados a permissões.

> [card] [API de Identidade](https://docs.truthlocks.com/api-reference/identity/orgs.md)
>
> Gerencie usuários e funções programaticamente.


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