Tokens de API
Um token de API dá acesso à API do Coda Cloud sem login interativo: em pipelines, scripts e na CLI. Todo token tem escopos, validade obrigatória e, de preferência, vínculo com uma organização e com projetos.
Tipos de token
| Tipo | Prefixo | Dono | Onde criar |
|---|---|---|---|
| Pessoal | atl_pat_ | Você. O token age com as suas permissões, dentro dos escopos escolhidos | Menu da conta › Tokens de API |
| De conta de serviço | atl_sat_ | Uma conta de serviço da organização, que não depende de nenhuma pessoa | Configurações › Contas de serviço › conta |
Para automações da organização, prefira a conta de serviço: a pipeline continua funcionando quando quem a configurou sai da organização.
O segredo tem o prefixo, 40 caracteres aleatórios e 6 caracteres de verificação (checksum). O checksum permite reconhecer um token do Coda Cloud e descartar valores digitados errado ou forjados. O valor aparece uma única vez, na criação: copie na hora e guarde num cofre ou no segredo da pipeline. A plataforma guarda só um hash do token.
Escopos
Cada token tem uma lista de escopos recurso:ação. Escrever (write) inclui ler (read) o mesmo recurso. O catálogo completo, com o papel mínimo de cada escopo, está em GET /api/v1/meta/api-scopes.
| Escopo | Permite | Papel mínimo |
|---|---|---|
orgs:read | Ler as organizações e o uso | Viewer |
projects:read | Listar e ler projetos | Viewer |
projects:write | Criar, renomear, arquivar e excluir projetos | Admin |
environments:read | Listar e ler ambientes | Viewer |
environments:write | Criar e alterar ambientes | Developer |
apps:read | Ler aplicações, instâncias, métricas e status | Viewer |
apps:write | Criar, alterar e excluir aplicações, builds e vínculos de repositório | Developer |
deployments:read | Ler deployments e versões | Viewer |
deployments:write | Deploy, rollback, promoção e escala | Developer |
config:read | Ler variáveis de configuração | Viewer |
config:write | Criar e remover variáveis de configuração | Developer |
secrets:read | Ler metadados de segredos (nomes, versões, datas), nunca o valor | Viewer |
secrets:write | Criar, rotacionar e remover segredos | Developer |
domains:read | Ler domínios, rotas, certificados e WAF | Viewer |
domains:write | Adicionar, verificar e remover domínios, rotas e configurações de WAF | Developer |
logs:read | Ler logs das aplicações | Viewer |
exec:run | Abrir sessões de terminal e exec | Developer |
audit:read | Ler a auditoria da organização | Viewer |
costs:read | Ler uso e custos | Viewer |
billing:read | Ler plano, assinatura e faturas | Viewer |
mcp:use | Usar o servidor MCP dos assistentes de IA; os demais escopos continuam limitando cada ferramenta | Viewer |
O formulário oferece modelos prontos:
| Modelo | Escopos |
|---|---|
| Somente leitura | Todos os escopos :read |
| Deploy por CI | apps:read, deployments:write (com deployments:read), config:read e logs:read |
| Completo | Todos os escopos do catálogo |
Escolha o menor conjunto que resolve a tarefa.
Permissão efetiva: escopo e papel
Um pedido feito com token só é aceito quando as duas condições valem:
- o token tem um escopo que cobre a operação; e
- o papel atual do dono na organização permite a operação.
O escopo nunca aumenta o papel. Um Viewer com deployments:write continua sem conseguir fazer deploy, e um token criado por alguém que depois foi rebaixado passa a valer só o que o papel novo permite.
| Situação | Resposta |
|---|---|
| Falta o escopo | 403 insufficient_scope, com o cabeçalho WWW-Authenticate: Bearer error="insufficient_scope", scope="<escopos>" |
| Falta o papel | 403, como no portal |
| Operação só para login interativo | 403 api_token.not_allowed |
Operações só com login interativo
Algumas operações sensíveis não têm escopo e só funcionam no portal ou na CLI com coda login: gerenciar tokens, membros e papéis, transferir a propriedade, excluir ou desativar a organização, conta de faturamento e método de pagamento, aceite de termos e contas de serviço. Com token, elas respondem 403 api_token.not_allowed. Criar um token usando outro token responde 403 api_token.interactive_required.
Toda rota da API precisa declarar o escopo exigido ou ser marcada como exclusiva de login interativo. Uma rota sem declaração recusa tokens.
Vínculo com organização e projetos
| Vínculo | Efeito |
|---|---|
| Organização | O token só acessa essa organização. As outras respondem 404, mesmo que você seja membro delas |
| Projetos | O token só acessa esses projetos. Outro projeto responde 404, e a lista de projetos vem filtrada |
| Projetos, em rota de organização inteira | Custos, auditoria, membros, uso e faturamento respondem 403 api_token.project_restricted |
Um token pessoal sem organização alcança todas as organizações de que você participa, inclusive as que você entrar depois. O portal mostra um aviso nesse caso: prefira vincular. Tokens de conta de serviço são sempre vinculados à organização da conta e herdam a restrição de projetos dela.
Criar um token pessoal
- Abra o menu da conta › Tokens de API › Novo token.
- Informe o nome, o modelo ou os escopos, a organização, os projetos (opcional) e a validade.
- Confirme o segundo fator se o portal pedir.
- Copie o token exibido.
Pela CLI, com login interativo:
coda tokens create ci-acme --org acme --scope apps:read --scope deployments:write --expires-in-days 30
--token-project <projeto> (repetível, exige --org) restringe o token a projetos. O segredo sai uma única vez no stdout.
Validade: obrigatória, de 1 a 365 dias.
Login recente: criar um token exige ter confirmado o login (com segundo fator) nos últimos 5 minutos. Sem isso, a API responde 401 step_up_required e o portal pede a confirmação. O token registra se foi criado com MFA.
Cada usuário tem até 10 tokens pessoais ativos.
Usar
Envie o token no cabeçalho Authorization:
curl -H "Authorization: Bearer $CODA_TOKEN" https://api.<domínio>/api/v1/orgs
Na CLI, use CODA_TOKEN ou coda login --with-token (veja CLI).
Último uso e expiração
A lista de tokens mostra, para cada um, os escopos, o vínculo, a validade e o último uso: data, IP de origem e cliente (User-Agent, por exemplo atlas-cli/1.0.0). O último uso é atualizado no máximo uma vez por minuto.
Sete dias antes de expirar, o dono recebe um e-mail com o nome do token e a data, uma única vez. Para token de conta de serviço, o aviso vai para os Owner e Admin da organização. Token expirado ou revogado responde 401.
Rotacionar sem interromper
Rotacionar cria um token novo com o mesmo nome, escopos, vínculos e duração, e mostra o valor novo uma vez. O token atual continua valendo durante a sobreposição, de 0 a 168 horas (0 encerra o atual na hora). Nesse intervalo, troque o segredo na pipeline.
POST /api/v1/me/api-tokens/{id}/rotate
{ "overlapHours": 24 }
Um token já rotacionado não pode ser rotacionado de novo (409): rotacione o novo.
Revogar
| Quem | Onde | O quê |
|---|---|---|
| O dono | Menu da conta › Tokens de API | Os próprios tokens |
Owner e Admin | Configurações › Tokens | Todos os tokens com acesso à organização: pessoais vinculados a ela e de contas de serviço. Nunca o segredo |
A revogação vale na hora. Quando um membro é removido da organização, os tokens pessoais dele vinculados a ela são revogados. Toda criação, rotação e revogação entra na auditoria, sem o segredo.
Rate limit por token
Cada token tem limites próprios por minuto, definidos pelo plano da organização do token:
| Limite | Chave | Padrão |
|---|---|---|
| Requisições por minuto | apiTokens.requestsPerMinute | 600 |
| Mutações por minuto | apiTokens.mutationsPerMinute | 60 |
Acima do limite, a API responde 429 com Retry-After. Um token pessoal sem organização usa os valores padrão. O login interativo não usa esses limites.
Token vazado
Se um token apareceu num repositório, log ou chat:
- Revogue o token no portal (ou peça a um
Owner/Adminda organização). - Crie outro e troque nos lugares que o usam.
- Consulte a auditoria filtrando pela credencial para ver o que foi feito com ele.
Qualquer pessoa pode reportar um token do Coda Cloud encontrado em público, sem login:
curl -X POST https://api.<domínio>/api/v1/public/token-revocations \
-H 'Content-Type: application/json' \
-d '{"tokens": ["atl_pat_..."]}'
O endpoint aceita até 100 segredos por chamada e responde sempre 202, sem dizer quais existiam. Os tokens ativos encontrados são revogados com o motivo leak-report, e o dono recebe um e-mail. Valores com checksum inválido são descartados. O limite é de 10 chamadas por minuto por IP.
Auditoria
Toda mutação registra por qual canal foi feita (portal, cli, api-token, service-account ou mcp), o id da credencial e o cliente. Na página Auditoria, filtre por canal e por credencial para ver tudo o que um token fez.
Tokens antigos (legados)
Os tokens criados antes dos escopos continuam funcionando com todos os escopos do catálogo e expiram 90 dias depois da migração, se não tinham validade. A lista mostra o selo "legado, expira em …". Rotacione ou troque por um token novo com os escopos mínimos.
API
| Método e rota | O que faz |
|---|---|
GET /api/v1/meta/api-scopes | Catálogo de escopos |
GET, POST /api/v1/me/api-tokens | Lista e cria tokens pessoais (name, scopes, expiresInDays, organizationId e projectIds opcionais) |
POST /api/v1/me/api-tokens/{id}/rotate | Rotaciona (overlapHours) |
DELETE /api/v1/me/api-tokens/{id} | Revoga um token pessoal |
GET /api/v1/orgs/{orgId}/api-tokens | Tokens com acesso à organização, com filtros por dono, tipo e situação (Owner e Admin) |
DELETE /api/v1/orgs/{orgId}/api-tokens/{id} | Revoga um token com acesso à organização (Owner e Admin) |
POST /api/v1/public/token-revocations | Reporte de token vazado (anônimo) |
As rotas de gestão de tokens só aceitam login interativo.