API tokens let a script, a CI pipeline or your own tooling drive Orbit without a browser session: trigger deployments, report CI check results, download build artifacts, manage cron jobs and more…

Tokens da API Orbit e a REST API

Os tokens da API permitem que um script, um pipeline de CI ou suas próprias ferramentas controlem o Orbit sem uma sessão de navegador: disparar implantações, relatar resultados de verificação de CI, baixar artefatos de compilação, gerenciar trabalhos cron e muito mais, tudo autenticado com um token Bearer que você mesmo define o escopo.

Onde os Tokens Estão

Abra o Orbit e escolha Tokens na navegação de nível superior. A página é intitulada API Access Tokens e estabelece sua própria regra logo no início: tokens são mostrados uma única vez no momento da criação.

A documentação completa do endpoint fica a um clique de distância. O card API Reference tem um botão View docs que abre a referência no painel para cada endpoint do Orbit.

API Access Tokens page in Orbit

Criando um Token

Clique em New token.
Dê um Token name. Nomeie-o conforme a coisa que o usará, por exemplo o fluxo de trabalho de CI, para que o inventário seja legível depois.
Escolha seus Scopes.
Opcionalmente defina um Expiry. Deixe em branco para um token que não expira.
Clique em Create token.

O token bruto é exibido uma única vez, em um heading One-time reveal, com um botão de cópia. Cole-o diretamente em seu armazenamento de secrets de CI. Não há maneira de vê-lo novamente: apenas um hash SHA-256 do token é armazenado, por isso nem mesmo a Kapsule pode recuperá-lo para você.

Uma conta pode conter até 20 tokens ativos. Criar um vigésimo primeiro é recusado com uma mensagem pedindo para você revogar um existente primeiro.

Nunca cole um token em uma mensagem de chat, um ticket, um commit ou uma captura de tela. Um token com deploy:write pode enviar código para produção, e um token com env:write pode ler e substituir sua configuração de ambiente. Trate-o exatamente como você trataria uma senha.

Escopos

Os escopos são o ponto principal dos tokens: cada um carrega apenas as permissões que você deu a ele.

Escopo	Concede
`deploy:write`	Disparar e gerenciar implantações
`project:read`	Ler detalhes do projeto e ambiente
`project:write`	Alterar configurações do projeto
`env:read`	Ler metadados de variáveis de ambiente
`env:write`	Definir e excluir variáveis de ambiente

Um novo token usa como padrão deploy:write e project:read, que é o que um pipeline de implantação precisa e nada mais.

Conceda o menor conjunto que faz o trabalho. Um token que apenas precisa relatar um resultado de CI não precisa de project:write. Um script de monitoramento somente leitura não precisa de nenhum escopo de escrita. Cada endpoint na referência lista o escopo mínimo que ele requer.

Usando um Token

A autenticação é um header Bearer contra a base da API, https://kapsulehost.com:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

A página Tokens contém um snippet CI/CD usage pronto para usar e um fluxo de trabalho starter do GitHub Actions. O starter é salvo como .github/workflows/orbit-deploy.yml e precisa de dois secrets do repositório, ORBIT_TOKEN e ORBIT_PROJECT_ID. Copie ambos da página em vez de transcrevê-los.

O Que a API Cobre

A referência no painel documenta cada área com seus parâmetros e escopo necessário:

Deployments: dispara uma implantação, opcionalmente em um branch nomeado, opcionalmente agendada para um tempo futuro entre cinco minutos e trinta dias à frente, com uma nota de até 500 caracteres. A listagem suporta busca difusa em commit, mensagem, branch e autor, além de filtros em branch, status e ambiente, com paginação de cursor até 100 resultados por página.
Deployment checks: registra um quality gate no início do seu trabalho de CI, então relata o resultado quando ele termina. Uma verificação required que falha move a implantação para FAILED e reverte o ambiente para a implantação bem-sucedida anterior, que é como você torna seu próprio conjunto de testes um deploy gate genuíno.
Branch protection: regras de padrão glob que bloqueiam implantações automáticas até que as verificações necessárias passem e, opcionalmente, alguém aprove. Até dez regras por projeto.
Build artifacts: obtenha uma URL de download pré-assinada para o output compilado de uma implantação bem-sucedida. A URL é válida por quinze minutos.
Project transfer: inicie, cancele e verifique o status de uma transferência para outra conta. Veja Transferring an Orbit Project.
Cron jobs: liste, crie, atualize, delete, dispare e leia histórico de execução. Veja Orbit Cron Jobs.
Timeline annotations: crie e gerencie anotações de incidente, lançamento, milestone, nota e flag. Veja Orbit Timeline Annotations.
Status page: leia e escreva a configuração da página de status pública. Veja Orbit Status Page.
Edge functions: liste, crie, atualize e implante handlers de edge. Veja Orbit Edge Functions.

A autenticação de sessão do painel funciona junto com tokens Bearer, então um endpoint que você pode chamar de seu navegador geralmente pode ser chamado de um script também.

Turbo Remote Cache

A página Tokens também contém um card Remote Build Cache. Ele implementa o Turborepo Remote Cache Protocol, permitindo que um monorepo compartilhe caches de compilação entre execuções de CI e máquinas de desenvolvimento.

Habilite-o no card, copie o token que ele gera e defina-o junto com seu ID de conta como TURBO_TEAM em seu ambiente de CI. Artefatos de até 150 MB cada são aceitos. O card também oferece Rotate token e Disable.

Se o CI do seu monorepo passa a maior parte do tempo reconstruindo pacotes que não foram alterados, esta é a coisa de maior valor único nesta página.

Gerenciando o Inventário

O Token inventory lista cada token ativo com:

Quando foi Created.
Quando foi Last used, ou Never.
Quando Expires, com um badge expired uma vez que tenha expirado.

A coluna Last used é a que você deve auditar. Um token que nunca foi usado está mal configurado ou esquecido, e de qualquer forma é uma credencial espaçada fazendo nada. A própria dica da página diz claramente: revogue qualquer coisa que você não reconheça.

Revogando um Token

Clique no controle de revogação na linha. A confirmação é explícita: tudo autenticando com esse token perde acesso imediatamente, e isto não pode ser desfeito.

Revogue quando um pipeline é retirado, quando alguém com acesso aos seus secrets de CI sai, ou no momento que você suspeitar que um token vazou. Não há revogação parcial e nenhum período de tolerância, que é exatamente o que você quer no caso de vazamento.

Defina uma expiração em tokens que você cria para um trabalho único. Um token que expira se limpa; um token permanente criado para uma migração de dois dias ainda é válido dois anos depois.

Resolução de Problemas

401 Unauthorized. O header está errado ou o token foi revogado ou expirou. Verifique se o header é Authorization: Bearer <token> com um único espaço, e que seu secret de CI não tem uma quebra de linha à direita.

403 Forbidden. O token é válido mas carece do escopo para esse endpoint. A referência lista o escopo mínimo por endpoint. Os escopos são fixos na criação, portanto crie um novo token com o conjunto certo.

429 on creation. Você está no limite de vinte tokens. Revogue algo do inventário.

The artifact URL stops working. URLs pré-assinadas duram quinze minutos. Solicite uma nova em vez de armazenar a URL.

A scheduled deployment is rejected. O tempo agendado deve estar entre cinco minutos e trinta dias no futuro.

Onde Ir a Seguir

Deploying Your Project para saber o que uma implantação disparada realmente faz.
Orbit Deployment Pipeline para ver quais gates suas implantações de API atenderão.
Orbit Plan Limits para saber o que seu plano inclui.

Tokens da API Kapsule Orbit e a API REST