> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/settings/api-keys.md).
# Chaves de API
Crie, delimite, rode e revogue chaves de API no Kilo IoT — credenciais por integração para acesso REST e gRPC.
As chaves de API concedem aos sistemas externos acesso programático ao Servidor Kilo IoT. Use-as para integrar pipelines de CI/CD, sincronizar dados com plataformas de gestão de armazéns, alimentar scripts personalizados de análise ou relatórios, ligar sistemas SCADA ou automatizar a configuração através das suas próprias ferramentas. Cada chave está limitada exatamente às permissões de que precisa — nada mais. Se alguma chave alguma vez for comprometida, revoga-a ou faz a sua rotação sem afetar qualquer outra integração.
> **À procura de como *****usar***** a API?** Os protocolos (REST e gRPC), a autenticação e os exemplos estão cobertos na [API](/kilo-docs-pt/kilo-iot-server/api.md) secção. Esta página é sobre criar e gerir as chaves com as quais essas integrações se autenticam.
***
## Navegação
Ir para **Definições → Chaves de API** na barra lateral.
***
## Criar uma chave
1. Clica em **Criar chave de API** no canto superior direito.
2. Introduza um **Nome** para a chave. Isto é obrigatório. Escolha um nome que descreva a integração — por exemplo, "WMS-Sync-Production" ou "Analytics-Pipeline-Staging". Irá identificar e gerir esta chave pelo respetivo nome.
3. Opcionalmente, defina uma **Expira** data usando o seletor de datas. A data mais antiga que pode ser selecionada é hoje. Se ficar em branco, a chave permanece ativa indefinidamente. Defina uma data de expiração para acesso de contratados ou integrações temporárias.
4. Seleciona **Âmbitos** — é necessário, no mínimo, um âmbito. Marque apenas as permissões de que a integração realmente precisa. Consulte a [referência de âmbitos](#scope-reference) abaixo.
5. Clique no botão de confirmação para criar a chave.
### Visualização única
Após a criação, o valor completo da chave é mostrado **uma vez** com um botão de cópia. Surge um aviso:
> **"Copie esta chave agora. Não a poderá voltar a ver."**
Guarde imediatamente a chave num gestor de segredos ou num cofre. Quando fechar esta caixa de diálogo, o valor completo da chave desaparece — apenas o prefixo da chave permanece visível na tabela. Se a chave se perder, o único caminho de recuperação é a rotação.
***
## referência de âmbitos
Os âmbitos controlam o que a chave pode aceder. Cada âmbito tem uma **Leitura** variante (obter dados) e uma **Escrita** variante (criar, atualizar ou eliminar). Conceda apenas o conjunto mínimo de que a sua integração necessita.
Os âmbitos disponíveis podem depender da sua organização e do seu plano. As chamadas de histórico de sensor **histórico** e **última vez visto** usam um âmbito de telemetria separado em vez de *Dispositivos: Leitura* — consulte a [referência da API](/kilo-docs-pt/kilo-iot-server/api.md) para o âmbito exato que cada endpoint requer.
| Âmbito | Leitura concede acesso a | Escrita concede acesso a |
| ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------------- |
| **Comandos** | Ver definições de comandos do dispositivo e histórico de execução | Criar e editar comandos, e enviá-los para dispositivos |
| **Conexões** | Ver o estado e a configuração da ligação | Criar e modificar ligações |
| **Painéis** | Ver dashboards e dados de widgets | Criar, editar e eliminar dashboards e widgets |
| **Dispositivos** | Ver a lista de dispositivos e o estado do Gémeo Digital | Registar dispositivos, atualizar a configuração do dispositivo |
| **Eventos** | Ver o histórico de eventos do dispositivo | — |
| **Registos** | Ver registos do sistema e do dispositivo | Exportar registos |
| **Organizações** | Ver detalhes da organização e a filiação | Modificar as definições da organização e a filiação |
| **Regras** | Ver definições de regras e o estado da implementação | Criar, editar, implementar e eliminar regras |
| **Sensores** | Ver definições de métricas de sensores e modelos | Criar e modificar modelos de sensores |
| **Utilizadores** | Ver a lista de utilizadores e os dados do perfil | Convidar, atualizar e remover utilizadores |
**Princípio do menor privilégio:** conceda apenas os âmbitos que uma integração realmente usa — um script que lê a configuração do dispositivo precisa apenas de *Dispositivos: Leitura*, não de *Dispositivos: Escrita* nem de qualquer âmbito da organização. Um âmbito restrito limita o impacto caso uma chave alguma vez seja exposta.
***
## Tabela de chaves de API
A página Chaves de API lista todas as chaves da sua organização. As colunas da tabela são:
| Coluna | Descrição |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | A etiqueta atribuída na criação. |
| **Prefixo da chave** | Um prefixo curto do valor da chave — suficiente para confirmar que está a ver a chave certa sem expor o segredo completo. |
| **Âmbitos** | Etiquetas de permissão que mostram os âmbitos concedidos a esta chave. |
| **Estado** | **Ativa** (verde), **Rodada** (amarelo), ou **Revogada** (vermelho). |
| **Criada** | Carimbo de data/hora em que a chave foi criada pela primeira vez. |
| **Expira** | A data de expiração, ou "Nunca" se não tiver sido definida uma expiração. |
| **Última utilização** | O carimbo de data/hora da chamada autenticada à API mais recente que utilizou esta chave. |
As chaves são ordenadas por predefinição da mais recente para a mais antiga. Os ícones de rotação e revogação aparecem apenas nas chaves Ativas — um ícone de rotação para rodar e um ícone de lixo para revogar.
***
## Rodar uma chave
A rotação gera um novo valor de chave e desativa imediatamente a antiga. O estado da chave antiga muda para **Rodada** e já não pode autenticar qualquer pedido.
Use a rotação regularmente, ou sempre que uma chave possa ter sido exposta — por exemplo, se tiver sido registada acidentalmente, comprometida num repositório ou partilhada através de um canal inseguro.
1. Clique no ícone de rotação na linha da chave que pretende rodar.
2. É apresentada uma caixa de diálogo de confirmação:
> **"Rodar chave de API — Isto irá gerar uma nova chave e marcar a chave atual '\[name]' como rodada. A chave antiga deixará de funcionar."**
3. Confirme a rotação.
4. O novo valor da chave é apresentado **uma vez**. Copie-o imediatamente. Atualize todos os sistemas que usam a chave antiga antes de tentarem fazer a próxima chamada à API.
A chave rodada permanece visível na tabela com **Rodada** estado para efeitos de trilha de auditoria.
***
## Revogação de uma chave
A revogação desativa permanentemente uma chave. A ação não pode ser desfeita.
1. Clique no ícone de lixo na linha da chave.
2. É apresentada uma caixa de diálogo de confirmação:
> **"Revogar chave de API — Isto irá revogar permanentemente a chave de API '\[name]'. Esta ação não pode ser desfeita."**
3. Confirme a revogação.
O estado da chave muda para **Revogada** (vermelho) e permanece visível na tabela. As chaves revogadas não podem autenticar qualquer pedido. Surgem na trilha de auditoria, para que tenha um histórico completo de que chaves existiam e quando foram desativadas.
***
## Resultados esperados
Após criar uma chave:
* A chave aparece imediatamente na tabela com **Ativa** estado.
* A **Última utilização** a coluna mostra um travessão até a chave fazer a sua primeira chamada autenticada à API, e depois atualiza-se com cada utilização subsequente.
* As chaves apresentam uma data de expiração definida na criação; verifique o estado atual da chave na **Estado** coluna.
***
## Resolução de problemas
**Sem permissão para criar chaves de API:** A gestão de chaves de API requer direitos de acesso suficientes na sua organização. Contacte o administrador da sua organização se o **Criar chave de API** botão não estiver disponível.
**A chave foi perdida antes de ser copiada:** O valor completo da chave não pode ser recuperado. Clique em **Rodar** na linha da chave para gerar um novo valor. Atualize todas as integrações com a nova chave.
**Integração a devolver erros de autenticação:**
* Confirme que o estado da chave é **Ativa** (não Rodada nem Revogada).
* Verifique se a chave não ultrapassou a sua data de expiração.
* Verifique se a integração está a usar o valor correto da chave — compare o prefixo mostrado na tabela com o prefixo da chave em uso.
* Confirme que a chave tem o âmbito necessário para a operação que está a tentar realizar. Uma *Dispositivos: Leitura*-apenas falhará em operações de escrita.
**Chave revogada ou rodada ainda a aceitar pedidos:** As alterações entram em vigor imediatamente. Se uma integração ainda parecer estar a autenticar após a revogação, confirme que não está a usar uma chave diferente ou uma sessão em cache.
***
## Boas práticas
* **Menor privilégio** — Conceda apenas os âmbitos que cada integração realmente usa. Audite regularmente.
* **Nomeada pelo propósito** — Use nomes como "Warehouse-Sync-Prod", "Audit-Export-Script" ou "CI-Pipeline-Staging" para que qualquer membro da equipa possa identificar de imediato o proprietário e a função da chave.
* **Defina datas de expiração para acesso temporário** — Integrações de contratados, scripts de prova de conceito e projetos com prazo limitado devem sempre ter uma expiração. Elimine a necessidade de se lembrar de revogar manualmente.
* **Faça rotação segundo um calendário** — Trate a rotação como manutenção de rotina e não como resposta a incidentes. Um ciclo de rotação trimestral é uma base razoável para chaves de produção.
* **Armazene num gestor de segredos** — Nunca codifique chaves de forma fixa no código-fonte, em ficheiros de configuração ou em variáveis de ambiente comprometidas no controlo de versões. Use um gestor de segredos ou cofre e injete-as em tempo de execução.
* **Uma chave por integração** — Chaves separadas significam que pode revogar o acesso de um sistema sem afetar qualquer outro. Chaves partilhadas multiplicam o impacto de qualquer comprometimento individual.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/settings/api-keys.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
