# Token de API

Para usar a API `/v1` você precisa de um **token de API** (`nbk_…`). Ele pertence ao time, não a uma pessoa.

## Criar o token

1. No painel: **Time → Configurações → Tokens de API → Criar token**. Exige papel `admin` do time e confirmação
   recente de identidade (step-up).
2. Escolha o nome, os **escopos** e, opcionalmente, as galerias permitidas (por padrão, todas as do time):

   | 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) |

   Escopos de deploy, serviços, variáveis, domínios, volumes, bancos, logs e templates:

   | Escopo | Permite |
   |---|---|
   | `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 (o token precisa ter 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) |

   Um token também pode ser restrito a projetos específicos (`project_ids`). Detalhes em [Tokens e escopos](/seguranca/tokens-e-escopos/).

3. **O token (`nbk_…`) é mostrado uma única vez.** Guardamos só o hash. Perdeu? Revogue e crie outro.
4. Validade: 90 dias por padrão, máximo 1 ano. O token pertence ao **time** (não a uma pessoa) e nunca dá acesso a
   membros ou cobrança. Pode ser revogado a qualquer momento.
5. Envie **somente** no cabeçalho `Authorization: Bearer nbk_…`. **Nunca em query string** (a requisição é
   recusada com 401). **Cookies são ignorados** nestas rotas.

Variáveis usadas nos exemplos:

```bash
export NEBULAR_API=https://api.nebularws.com   # base URL
export NEBULAR_TOKEN=nbk_...                   # o seu token
export GALLERY=marcas-k7p2                     # a "key" de uma galeria (veja [Galerias e arquivos](/cdn/galerias/))
```

Todas as rotas ficam em `/v1` e o corpo de erro tem sempre o formato `{"error": "<codigo>", "message": "..."}`:
trate pelo `error` (estável), mostre o `message` (pt-BR) para pessoas.

## Verificação

Confirme o token e veja seus escopos e limites com `GET /v1/me` (espera `200`):

```bash
curl -sS "$NEBULAR_API/v1/me" \
  -H "Authorization: Bearer $NEBULAR_TOKEN"
```
```json
{"team": {"id": "01j9zk8xwdtry8pxzy0qqvb8k3", "name": "Acme", "plan": "hobby"},
 "token": {"id": "01j9zksf51s25jd7735q8fefyf", "name": "agente-deploy", "scopes": ["projects:read", "projects:write", "deploy"], "project_ids": null, "expires_at": "2026-11-10T12:00:00Z"}}
```

A resposta traz o time (`team`: `id`, `name`, `plan`) e o token (`token`: `id`, `name`, `scopes`, `project_ids` — `null` quando vale para todos os projetos — e `expires_at`). Os limites do time estão em `GET /v1/limits`.

Ou, só para galerias, listando as galerias do time (espera `200`):

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

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `401 unauthorized` | Token ausente, expirado, revogado ou enviado fora do cabeçalho. Não repita: confira o cabeçalho ou peça um token novo a um admin. |
| `403 forbidden` | O token não tem o escopo da rota. Peça um token com o escopo certo. |

Veja a [tabela completa de erros](/erros/tabela/) e [Tokens e escopos](/seguranca/tokens-e-escopos/).