Skip to main content
A chave de API deixa um script, o seu CI, a CLI, os SDKs ou um agente de IA usar a sua conta sem abrir o painel. Cada chave tem só as permissões que você marcar, caixa por caixa: uma chave de deploy envia o código e reinicia, mas não lê os seus arquivos nem a senha dos seus bancos.

​
Criar uma chave

1

Abra Chaves de API

No painel, em Chaves de API, clique em Nova chave e dê um nome que diga onde ela vai ser usada (“Deploy do GitHub”).
2

Escolha o modelo ou marque as caixas

Os modelos no topo marcam as caixas de uma vez. Mexeu numa caixa, o modelo vira Personalizado. Cada grupo tem o marcar o grupo, e cada caixa diz o que permite e o que não permite.
3

Confirme com a sua senha

A chave começa com cube_ e aparece uma vez só. Guarde num gerenciador de segredos ou numa variável de ambiente, como CUBE_API_KEY.

​
Modelos

Três permissões são perigosas e ficam fora dos modelos Leitura e Ler e escrever: files:read (o código pode ter segredos, como o .env), databases:credentials (dá acesso aos dados dos bancos) e projects:delete (excluir é definitivo). Marque só na chave que precisa e nunca coloque essa chave no código ou num repositório.

​
Permissões

Os nomes são em inglês, recurso:ação, iguais na API (requiredScope), na CLI, nos SDKs e no openapi.json. Cada rota da referência da API diz a permissão que pede.

​
O que nunca passa pela chave

Com nenhuma permissão, a chave não alcança a conta (senha, e-mail, verificação em duas etapas, sessões), a cobrança e o Pix, a equipe, as próprias chaves (uma chave nunca cria, edita nem revoga outra) e Cube AI. Algumas ações de projeto também ficam só no painel: excluir um backup ou uma versão, ligar o backup automático, os avisos por e-mail, o deploy pelo GitHub, gerar o certificado do acesso externo e excluir ou restaurar um banco. Nessas rotas, a chave recebe 403 api_key_not_allowed ou 401 not_authenticated.

​
Quando falta a permissão

A rota responde 403 com a permissão que falta em requiredScope:
No painel, em Chaves de API, abra o menu … da chave, clique em Editar permissões, marque a que falta e salve: a chave em si não muda, e as permissões novas valem no pedido seguinte. Editar pede a sua senha, entra na Atividade com o antes e o depois e, se a chave ganhou permissão, avisa por e-mail.

​
Numa equipe

Numa equipe, a chave age na conta da equipe e nunca passa do papel de quem a criou. Isso vale na criação, na edição e a cada pedido: se o papel de quem criou baixar depois, as rotas acima dele param de responder (403 insufficient_role). Excluir projetos pede o papel Admin, e o resgate de código de presente (gift-codes:redeem) é só do dono. Criar ou editar uma chave acima do papel responde 403 scope_above_role. As chaves da equipe são criadas por Admins e pelo dono, e param quando quem criou sai, é removido ou deixa de ser Admin.

​
Chaves criadas antes das permissões

As chaves de antes continuam funcionando, com exatamente o que já faziam, agora como caixas marcadas:
  • Leitura: projects:read, projects:logs, deployments:read, backups:read, databases:read, blob:read, blob-rules:read, domains:read.
  • Leitura e escrita: o da leitura mais projects:control, projects:deploy, projects:create, variables:read, variables:write, deployments:write, backups:write, databases:credentials, databases:write, blob:write, blob-rules:write, domains:write, gift-codes:redeem. Arquivos, configurações e excluir projetos ficam de fora: marque em Editar permissões se precisar.
  • Só Blob: blob:read e blob:write.

​
Boas práticas

  • Uma chave por uso (o CI, o bot, o agente), com só o que ele precisa: vazou uma, você revoga só ela.
  • Guarde a chave numa variável de ambiente ou no gerenciador de segredos do CI, nunca no código.
  • Vazou? Revogue em Chaves de API: o pedido seguinte já recebe 401. Redefinir a senha pelo e-mail revoga todas as chaves.
  • Tudo o que a chave faz entra na Atividade com o nome dela (“pela API (chave Deploy do GitHub)”).