KapsuleHost fornece-lhe duas superfícies de programador: chaves API com âmbito para ler a sua conta programaticamente, e uma cache de construção remota que acelera as construções Turborepo e Nx nas suas máquinas e executores CI.
Nenhuma está ativada por defeito. Ambas são criadas a partir de Definições, e ambas lhe entregam um segredo exatamente uma vez.
Criar uma Chave API
As chaves API ficam em Definições, depois Segurança, no cartão Chaves API.
- Aceda a Definições, depois Segurança.
- Desloque até Chaves API e clique em Nova chave.
- Dê um nome à chave. O campo sugere "Nome da chave (ex. O meu script de automatização)". O nome é apenas para si, portanto faça-o indicar onde a chave será utilizada.
- Clique nos chips de âmbito para selecionar o que a chave pode fazer. Três âmbitos de leitura são pré-selecionados:
read:sites,read:emaileread:domains. Clique num chip para adicioná-lo ou removê-lo. - Clique em Criar.
A chave completa aparece uma vez, num painel verde com o título "Copiar agora". Copie-a diretamente para o seu armazenamento de segredos. Quando dispensar esse painel, a chave desaparece: apenas um prefixo curto é mantido, que é tudo o que a lista poderá mostrar-lhe novamente.
A chave nunca é exibida uma segunda vez e não pode ser recuperada. Se a perder, revogue essa chave e crie uma nova. Não a cole num documento partilhado, num ticket, num commit ou numa mensagem de chat.
Apenas as funções Proprietário e Admin podem criar uma chave. Qualquer outra função recebe um erro de permissões. Quando uma chave é criada, um alerta de segurança por correio eletrónico é enviado para o endereço de quem a criou, portanto uma inesperada vale a pena investigar imediatamente.
Os Âmbitos
Sete âmbitos são oferecidos:
| Âmbito | Concede |
|---|---|
read:sites | Leitura dos seus websites |
write:sites | Reservado para operações de escrita em websites |
read:email | Leitura das suas caixas de correio |
write:email | Reservado para operações de escrita em caixas de correio |
read:domains | Leitura dos seus domínios |
write:domains | Reservado para operações de escrita em domínios |
read:billing | Reservado para leitura de dados de faturação |
A API do cliente é apenas de leitura hoje. Os âmbitos write: e read:billing podem ser selecionados numa chave, mas nenhum ponto final do cliente atualmente os consome, portanto concedê-los não muda nada. Conceda apenas os âmbitos de leitura que realmente precisa e reveja a chave quando os pontos finais de escrita forem lançados.
Usar uma Chave
Envie a chave como um token portador no cabeçalho Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Três pontos finais aceitam uma chave API do cliente:
| Ponto Final | Âmbito Obrigatório | Devolve |
|---|---|---|
GET /api/v1/sites | read:sites | Os seus websites, com domínio, tipo de aplicação e estado |
GET /api/v1/domains | read:domains | Os seus domínios, com estado e data de expiração |
GET /api/v1/mailboxes | read:email | As suas caixas de correio |
Um pedido sem chave, com uma chave desconhecida ou com uma chave revogada devolve 401. Uma chave válida sem o âmbito certo devolve 403 com uma mensagem que nomeia o âmbito que era necessário. Cada chamada bem-sucedida atualiza o carimbo de data/hora da última utilização da chave.
Consulte suavemente. Estes pontos finais lêem dados de conta em direto, e um ciclo apertado contra eles é indistinguível do abuso. Uma vez por minuto é generoso para tudo o que um painel de controlo precisa; uma vez por hora é geralmente suficiente.
Rever e Revogar Chaves
A tabela Chaves API lista cada chave ativa por Nome, Prefixo (o início visível da chave) e Âmbitos. Clique em Revogar no final de uma linha para a desativar.
A revogação entra em vigor imediatamente e não há caixa de diálogo de confirmação. O próximo pedido usando essa chave falha com 401. Uma chave revogada não pode ser restaurada, portanto tenha certeza de que sabe o que a está a utilizar antes de clicar.
As chaves pertencem à conta, não à pessoa que as criou. Remover um colega de página Equipa não revoga as chaves que criaram. Construa uma revisão de chaves na sua desmobilização: remova a pessoa e venha aqui revogar tudo o que criou.
A criação e revogação de chaves são ambas registadas no registo de auditoria sob as ações api_key.*, com o ator e o endereço IP de origem.
A Cache de Construção Remota
A página Programador, no grupo Avançado da barra de definições, oferece uma Cache de Construção Remota. O painel descreve-a como uma forma de "Acelerar as construções Turborepo e Nx partilhando uma cache distribuída em máquinas e pipelines CI."
- Aceda a Definições, depois Programador.
- Clique em Ativar cache remota.
- Copie o token do painel com o título "Novo token gerado. Copie-o agora, não será exibido novamente".
Em seguida, defina duas variáveis de ambiente na sua configuração CI ou .env.local local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
O ID da equipa é o seu ID de conta KapsuleHost, mostrado nas instruções de configuração na mesma página.
A página apresenta a sua própria compatibilidade: Turborepo 1.x e posterior, Nx 16 e posterior, e qualquer ferramenta que implemente o mesmo protocolo de cache remota. Os artefatos são armazenados por conta e nunca são partilhados entre contas.
Dois controlos adicionais ficam no cartão:
- Rodar token emite um novo token e invalida o antigo. Qualquer trabalho CI ainda a manter o token antigo deixa de utilizar a cache, portanto rode e atualize os seus segredos em conjunto.
- Desativar desativa a cache inteiramente.
Escolher Entre os Dois
Resolvem problemas não relacionados e não são intercambiáveis.
Utilize uma chave API quando algo fora de KapsuleHost precisa de conhecer o estado da sua conta: um painel de estado que lista os seus sites, um script que o avisa sobre domínios que estão prestes a expirar, uma exportação de inventário.
Utilize a cache de construção remota quando as suas construções são lentas porque cada máquina e cada execução CI reconstrói os mesmos pacotes inalterados. Não tem nada a ver com os seus sites alojados e não lê os seus dados de conta.
Resolução de Problemas
Cada pedido devolve 401. Confirme que enviou o cabeçalho como Authorization: Bearer <key> com um único espaço, que a chave não foi truncada quando a copiou e que não foi revogada. Compare o início da sua chave com a coluna Prefixo para se certificar de que está a utilizar a chave que pensa estar a utilizar.
Um pedido devolve 403 nomeando um âmbito. A chave não tem esse âmbito. Os âmbitos são fixados quando a chave é criada, portanto crie uma substituição com os âmbitos certos e revogue a antiga.
Não consigo ver o cartão Chaves API. Está na página Segurança, não na página Programador. A página Programador contém apenas a cache de construção.
O botão Nova chave não faz nada. A sua função está abaixo de Admin. Peça ao Proprietário ou a um Admin.
As construções não estão a atingir a cache. Verifique se ambos TURBO_TOKEN e TURBO_TEAM estão presentes no ambiente de construção, se o token não foi rodado desde que o definiu e se a página ainda mostra o distintivo Ativo.
Apareceu uma chave que não criei. Trate-a como um compromisso. Revogue-a e depois trabalhe através de Segurança da Conta e verifique o registo de auditoria para ver o que mais mudou.