# Chaves de API e Acesso de Programador Source: https://support.kapsulehost.com/pt-pt/developer-api-access 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**. ![Cartão Chaves API nas definições de segurança do KPanel com os chips de âmbito visíveis](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp) 1. Aceda a **Definições**, depois **Segurança**. 2. Desloque até **Chaves API** e clique em **Nova chave**. 3. 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. 4. 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:email` e `read:domains`. Clique num chip para adicioná-lo ou removê-lo. 5. 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. > **Warning:** 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 | > **Note:** 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`. ```sh 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. > **Tip:** 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. > **Important:** 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](https://support.kapsulehost.com/pt-pt/account-team-members) 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](https://support.kapsulehost.com/pt-pt/account-audit-log) 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." 1. Aceda a **Definições**, depois **Programador**. 2. Clique em **Ativar cache remota**. 3. 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: ```sh TURBO_TOKEN= TURBO_TEAM= ``` 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 ` 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](https://support.kapsulehost.com/pt-pt/account-security) e verifique [o registo de auditoria](https://support.kapsulehost.com/pt-pt/account-audit-log) para ver o que mais mudou.