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

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.