Conta
Chaves de API e Acesso para Desenvolvedores
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
Chaves API e Acesso para Desenvolvedor
Kapsule oferece duas superfícies para desenvolvedores: chaves API com escopo para ler sua conta programaticamente, e um cache de compilação remota que acelera compilações Turborepo e Nx em suas máquinas e runners de CI.
Nenhuma é ativada por padrão. Ambas são criadas em Settings, e ambas fornecem um segredo exatamente uma vez.
Criando uma Chave API
As chaves API ficam em Settings, depois Security, no card API Keys.
- Vá para Settings, depois Security.
- Role até API Keys e clique em New key.
- Dê um nome à chave. O campo sugere "Key name (e.g. My automation script)". O nome é apenas para você, então deixe-o indicar onde a chave será usada.
- Clique nos chips de escopo para selecionar o que a chave pode fazer. Três escopos de leitura são pré-selecionados:
read:sites,read:emaileread:domains. Clique em um chip para adicioná-lo ou removê-lo. - Clique em Create.
A chave completa aparece uma vez, em um painel verde intitulado "Copy now". Copie-a direto para seu armazenamento de segredos. Quando você descartar esse painel, a chave desaparece: apenas um prefixo curto é mantido, que é tudo que a lista poderá mostrar novamente.
A chave nunca é exibida uma segunda vez e não pode ser recuperada. Se perdê-la, revogue essa chave e crie uma nova. Não a cole em um documento compartilhado, um ticket, um commit ou uma mensagem de chat.
Apenas os papéis Owner e Admin podem criar uma chave. Qualquer outro papel recebe um erro de permissões. Quando uma chave é criada, um email de alerta de segurança vai para o endereço de quem a criou, então um inesperado vale a pena investigar imediatamente.
Os Escopos
Sete escopos são oferecidos:
| Escopo | Concede |
|---|---|
read:sites | Leitura de seus sites |
write:sites | Reservado para operações de escrita em sites |
read:email | Leitura de suas caixas de correio |
write:email | Reservado para operações de escrita em caixas de correio |
read:domains | Leitura de seus domínios |
write:domains | Reservado para operações de escrita em domínios |
read:billing | Reservado para leitura de dados de faturamento |
A API do cliente é apenas leitura hoje. Os escopos write: e read:billing podem ser selecionados em uma chave, mas nenhum endpoint de cliente consome-os atualmente, portanto concedê-los não muda nada. Conceda apenas os escopos de leitura que realmente precisa e revise a chave quando endpoints de escrita forem lançados.
Usando uma Chave
Envie a chave como um bearer token no header Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Três endpoints aceitam uma chave API do cliente:
| Endpoint | Escopo necessário | Retorna |
|---|---|---|
GET /api/v1/sites | read:sites | Seus sites, com domínio, tipo de aplicação e status |
GET /api/v1/domains | read:domains | Seus domínios, com status e expiração |
GET /api/v1/mailboxes | read:email | Suas caixas de correio |
Uma requisição sem chave, com uma chave desconhecida, ou com uma chave revogada retorna 401. Uma chave válida sem o escopo certo retorna 403 com uma mensagem nomeando o escopo que era necessário. Cada chamada bem-sucedida atualiza o timestamp de último uso da chave.
Faça polling com cuidado. Esses endpoints leem dados de conta ao vivo, e um loop fechado contra eles é indistinguível de abuso. Uma vez por minuto é generoso para qualquer coisa que um dashboard precisa; uma vez por hora é geralmente suficiente.
Revisando e Revogando Chaves
A tabela de API Keys lista cada chave ativa por Name, Prefix (o início visível da chave) e Scopes. Clique em Revoke no final de uma linha para cancelá-la.
Revogar entra em vigor imediatamente e não há diálogo de confirmação. A próxima requisição usando essa chave falha com 401. Uma chave revogada não pode ser restaurada, portanto certifique-se de saber o que está usando antes de clicar.
As chaves pertencem à account, não à pessoa que as criou. Remover um colega de trabalho de the Team page não revoga as chaves que eles criaram. Incorpore uma revisão de chaves em seu offboarding: remova a pessoa, depois venha aqui e revogue qualquer coisa que eles criaram.
A criação e revogação de chaves são ambas registradas em the audit log sob as ações api_key.*, com o ator e o endereço IP de origem.
O Cache de Compilação Remota
A página Developer, no grupo Advanced da barra de configurações, oferece um Remote Build Cache. O painel o descreve como uma forma de "Accelerate Turborepo and Nx builds by sharing a distributed cache across machines and CI pipelines."
- Vá para Settings, depois Developer.
- Clique em Enable remote cache.
- Copie o token do painel intitulado "New token generated. Copy it now, it won't be shown again".
Depois defina duas variáveis de ambiente em sua configuração de CI ou .env.local local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
O team ID é seu ID de conta Kapsule, mostrado nas instruções de configuração na mesma página.
A página declara sua própria compatibilidade: Turborepo 1.x e posterior, Nx 16 e posterior, e qualquer ferramenta implementando o mesmo protocolo de cache remoto. Artefatos são armazenados por conta e nunca são compartilhados entre contas.
Dois controles adicionais ficam no card:
- Rotate token emite um novo token e invalida o antigo. Qualquer job de CI ainda mantendo o token antigo para de usar o cache, portanto rotacione e atualize seus segredos juntos.
- Disable desativa o cache completamente.
Escolhendo Entre Os Dois
Eles resolvem problemas não relacionados e não são intercambiáveis.
Use uma API key quando algo fora do Kapsule precisa conhecer o estado de sua conta: um quadro de status que lista seus sites, um script que o avisa sobre domínios expirando em breve, uma exportação de inventário.
Use o remote build cache quando suas compilações são lentas porque toda máquina e toda execução de CI reconstrói os mesmos pacotes inalterados. Não tem nada a ver com seus sites hospedados e não lê dados de sua conta.
Se você estiver implantando a partir de Git em vez de chamar uma API, veja Kapsule Orbit. Ele compila e envia a partir de seu repositório diretamente, com cache de compilação tratado para você.
Solução de Problemas
Toda requisição retorna 401. Confirme que você enviou o header como Authorization: Bearer <key> com um único espaço, que a chave não foi truncada quando você a copiou, e que ela não foi revogada. Compare o início de sua chave com a coluna Prefix para ter certeza de que está usando a chave que pensa estar.
Uma requisição retorna 403 nomeando um escopo. A chave não carrega esse escopo. Escopos são fixos quando a chave é criada, portanto crie uma substituição com os escopos corretos e revogue a antiga.
Não consigo ver o card API Keys. Ele está na página Security, não na página Developer. A página Developer contém apenas o cache de compilação.
O botão New key não faz nada. Seu papel está abaixo de Admin. Peça ao Owner ou a um Admin.
Compilações não estão atingindo o cache. Verifique que ambos TURBO_TOKEN e TURBO_TEAM estão presentes no ambiente de compilação, que o token não foi rotacionado desde que você o definiu, e que a página ainda mostra o badge Active.
Uma chave que não criei apareceu. Trate-a como uma comprometida. Revogue-a, depois trabalhe através de Account Security e verifique the audit log para o que mais mudou.