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

No painel: Time → Configurações → Tokens de API → Criar token. Exige papel admin do time e confirmação recente de identidade (step-up).

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.

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. 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.
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:

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

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

{"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):

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 e Tokens e escopos.