# Tokens e escopos

## Escopos

| Escopo | Permite |
|---|---|
| `assets:read` | listar galerias e arquivos, consultar detalhes e status de varredura |
| `assets:write` | enviar, versionar e excluir arquivos |
| `galleries:manage` | criar galerias (um token restrito a galerias específicas **não** cria galeria: 403) |
| `projects:read` | listar e ler projetos, serviços, deploys, domínios e bancos |
| `projects:write` | criar, editar e apagar projetos e serviços |
| `deploy` | disparar deploy e rollback, enviar fonte |
| `env:read` | ler nomes e valores **não sensíveis** de variáveis |
| `env:write` | criar, alterar e apagar variáveis |
| `env:reveal` | ver valores sensíveis (`?resolved=true`): exige que o token tenha sido criado com step-up **e** com este escopo explícito |
| `domains:write` | anexar e remover domínios |
| `volumes:write` | criar e apagar volume |
| `databases:write` | criar, apagar, rotacionar credencial, backup e restore de bancos |
| `logs:read` | ler logs de build e de runtime |
| `templates:deploy` | instanciar templates (ex.: WordPress) |

Princípio do menor privilégio: peça só o que a tarefa usa. Um agent que só publica imagens na CDN precisa de `assets:write`, não de `deploy`.

## Restrições

- **Por projeto** (`project_ids`): o token só enxerga e age nos projetos listados. Os demais projetos do time respondem `404`, como se não existissem.
- **Por galeria**: o token só enxerga as galerias permitidas.

## Regras

- O token (`nbk_…`) é mostrado **uma única vez**; guardamos só o hash. Perdeu? Revogue e crie outro.
- Validade: 90 dias por padrão, máximo 1 ano. Pode ser revogado a qualquer momento.
- O token pertence ao **time**, não a uma pessoa, e nunca dá acesso a membros ou cobrança.
- Criar um token exige papel `admin` e confirmação recente de identidade (step-up).
- Valores sensíveis (senhas de banco, `DATABASE_URL`, segredos gerados) só aparecem em claro com `env:reveal`; sem ele ficam mascarados.
- Envie somente em `Authorization: Bearer`. **Nunca em query string** (recusado com 401). Cookies são ignorados.
- Guarde em segredo do ambiente (CI, cofre). Nunca em repositório, log ou prompt. Exemplos desta documentação usam sempre `nbk_EXEMPLO`.

## Verificar o que o token pode

```bash
curl -sS "$NEBULAR_API/v1/me" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```

`403 forbidden` = falta o escopo da rota (peça um token novo); `404` pode significar que o recurso está fora dos `project_ids` do token. Veja [Tabela de erros](/erros/tabela/).