Autenticação e visão geral (referência)

API pública da Nebular para agents e automações: gerencie projetos, serviços, deploys, variáveis, domínios, volumes, bancos e templates e as galerias de arquivos servidas pela CDN (*.nebularcdn.com). Todas as rotas ficam em /v1, usam apenas Authorization: Bearer e respondem JSON (application/json; charset=utf-8, sempre Cache-Control: no-store). Esta especificação é servida em GET /v1/openapi.json (pública) e é validada contra o código a cada mudança.

Como obter um token

No painel: Time → Configurações → Tokens de API. A criação exige papel admin do time e confirmação recente de identidade (step-up). O token tem o formato nbk_<…>, é exibido uma única vez (guardamos apenas o hash SHA-256), vale 90 dias por padrão (máximo 1 ano) e pode ser revogado a qualquer momento. Ele pertence ao time, nunca a uma pessoa. Pode ser restrito a algumas galerias (assets:*) e/ou a alguns projetos (project_ids).

O token vai somente no cabeçalho Authorization: Bearer nbk_…. Nunca o envie em query string. Cookies são ignorados nestas rotas (não há CSRF por construção) e as rotas de sessão do painel não aceitam Bearer. Cada operação indica os escopos exigidos na extensão x-required-scopes (todos são necessários) e, quando um escopo opcional muda a resposta, em x-optional-scopes.

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
projects:read	ler projetos, serviços, deployments, domínios, volumes, bancos e backups
projects:write	criar, editar e apagar projetos e serviços
deploy	disparar, cancelar e reverter deploys (serviço e grupo), enviar código-fonte
env:read	ler variáveis (valores sensíveis vêm null)
env:write	criar, alterar e apagar variáveis
env:reveal	ler valores sensíveis, resolved=true e credenciais de banco. Exige env:read e que o token tenha sido criado com confirmação de identidade (step-up)
domains:write	anexar e remover domínios
volumes:write	anexar, aumentar e apagar o volume
databases:write	criar, alterar, apagar, rotacionar, backup e restore de bancos
logs:read	ler log de build e de execução
templates:deploy	listar e instanciar templates

Token sem o escopo ⇒ 403 forbidden. Projeto de outro time, ou fora dos project_ids do token, é indistinguível de um projeto inexistente (404 not_found). GET /v1/me e GET /v1/limits aceitam qualquer token válido.

Projetos e serviços

{p} nas rotas aceita o id (26 caracteres) ou o slug do projeto; {s} aceita o id ou o nome do serviço. Todo projeto nasce com um serviço web padrão. Variáveis podem referenciar outros serviços com ${{servico.VAR}} (ex.: ${{db.MYSQL_HOST}}); essas referências definem a ordem do deploy de grupo e são validadas no disparo.

Deploys são assíncronos

POST …/deployments, POST …/deploy, rollback, backup e restore respondem 202 com um recurso em andamento. Acompanhe por polling com backoff (comece em 2 s e dobre até 15 s; não há webhooks neste ciclo):

• deployment: queued → building → deploying → ready, ou failed, blocked, canceled, superseded; em failed, error traz code, message e details;
• deploy de grupo: running → ready | failed | canceled, com o estado de cada serviço em items[].status;
• job de banco: queued → running → done | failed;
• domínio: pending_dns → verifying → active | error.

Idempotência

Todo POST que cria ou dispara aceita Idempotency-Key (8 a 128 caracteres [A-Za-z0-9._:-]). Mesma chave + mesmo pedido em 24 h devolve a mesma resposta (com Idempotent-Replay: true); mesma chave com pedido diferente ⇒ 422 idempotency_conflict; chave malformada ⇒ 400. Só respostas 2xx são gravadas, então repetir depois de uma falha executa de verdade. O upload de arquivos de galeria tem regra própria (409 idempotency_conflict, mais abaixo).

Paginação

Listas devolvem {"items": […], "next_cursor": "…"|null, "has_more": bool}. Passe next_cursor em ?cursor= para a página seguinte e use ?limit= de 1 a 200 (padrão 50). O cursor é opaco; cursor malformado ⇒ 400 invalid_request. Deployments, backups e a lista de projetos vêm do mais novo para o mais antigo; as demais do mais antigo para o mais novo (variáveis por nome).

Segredos

Variáveis marcadas sensitive nunca voltam em claro por padrão (value: null); a resposta de PUT nunca ecoa um valor sensível; logs saem com segredos mascarados. Credenciais de banco só saem em POST …/credentials (nunca GET), com env:reveal, e a leitura é auditada.

Limites

• Plano do time: serviços, memória, volumes, bancos e deploys por hora (GET /v1/limits). Ao atingir ⇒ 422 quota_exceeded.
• Corpo JSON até 16 KiB (variáveis até 96 KiB por variável e 1 MiB no lote; serviços e templates até 64 KiB); código-fonte (multipart) até 512 MB.
• Galerias: 25 MB por arquivo (imagens também limitadas a 40 megapixels); cota por time no bucket compartilhado de 5 GB e 10 000 arquivos. Nomes de arquivo: até 4 segmentos separados por / (3 barras), cada um em [a-z0-9._-], até 200 caracteres, sem .., sem segmento iniciando com . e com o primeiro segmento diferente de 12 caracteres hexadecimais minúsculos; únicos dentro da galeria. Nome inválido ⇒ 400 invalid_request.
• Rate-limit por token e por IP: ao receber 429, espere Retry-After segundos.

Classes de arquivo e como cada uma é servida

O tipo é detectado pelo conteúdo (magic bytes), nunca pela extensão ou pelo Content-Type enviado. Extensão divergente do conteúdo em executável/documento é recusada (415 extension_mismatch).

Classe	Exemplos	Servido como
image	png, jpeg, webp, gif, avif	inline, transformável (?w=, ?q=)
svg	svg	inline só se passar na varredura de SVG, com CSP restritiva
font	woff2, woff, ttf, otf	inline, CORS *
media	mp4, webm, mp3, ogg	inline, com Accept-Ranges
document	pdf, txt, csv, json	Content-Disposition: attachment; texto sempre text/plain
markup	html, htm, xhtml, xml	nunca renderiza: attachment + text/plain + CSP sandbox
archive	zip, tar.gz, 7z	attachment; arquivo cifrado ou impossível de varrer é recusado
binary	exe, msi, dmg, apk, deb, appimage, desconhecido	attachment, application/octet-stream

Varredura (nada é publicado antes de clean)

Todo upload entra em quarentena e passa por antivírus, regras YARA, reputação por hash (só o hash sai da nossa infra), varredura específica de SVG e decodificação segura de imagens. Detectado ⇒ 422 e a amostra não é guardada. Scanner indisponível ⇒ o arquivo fica pending e não é publicado (resposta 202; consulte o GET do arquivo até scan.status sair de pending). Todo dia os arquivos publicados são reescaneados com as assinaturas novas: uma detecção move o arquivo para quarantined (deixa de ser servido, responde 451, o cache é purgado e o time é avisado).

Erros

Todo erro tem o formato {"error": "<code>", "message": "…", "details"?: {…}}; message é legível (pt-BR) e error é estável para tratamento programático (enumerado em Error.error). Algumas respostas trazem details (ex.: references em unresolved_reference/reference_cycle: apenas nomes, nunca valores). Os 5xx e 429 trazem Retry-After quando repetir faz sentido. Nos corpos de serviço, variável e deploy, um campo desconhecido (ex.: memory_mb solto no topo; o certo é {"resources": {"memory_mb": 1024}}) é recusado com 400 invalid_request, e a mensagem nomeia o campo, em vez de ser ignorado em silêncio.

Status	error
400	invalid_request, bad_json, bad_body
401	unauthorized (genérico de propósito: token ausente, inválido, expirado ou revogado)
403	forbidden
404	not_found
409	name_taken, slug_taken, project_quota_exceeded, project_not_empty, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, volume_exists, volume_in_use, volume_attached, backup_not_ready, gallery_not_empty, idempotency_conflict (upload de galeria)
413	too_large, payload_too_large
415	unsupported_media_type, unsupported_type, extension_mismatch, class_not_allowed
422	quota_exceeded, idempotency_conflict, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported
429	rate_limited
500	internal
503	unavailable, authz_unavailable, database_unavailable

Espelho do painel

O painel usa as mesmas operações em /api/teams/{tid}/… (sessão + CSRF, com confirmação de identidade em ações destrutivas). Essas rotas não fazem parte desta API pública e não aceitam Bearer.

Servidores

• https://api.nebularws.com — Produção

Esquemas de segurança

• bearer: http (bearer) Token de API de time (nbk_…) criado em Time → Configurações → Tokens de API. Somente no cabeçalho Authorization: Bearer; nunca em query string. Cookies são ignorados nestas rotas.