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 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
Clica em Criar chave de API no canto superior direito.
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.
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.
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 abaixo.
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 para o âmbito exato que cada endpoint requer.
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:
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.
Clique no ícone de rotação na linha da chave que pretende rodar.
É 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."
Confirme a rotação.
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.
Clique no ícone de lixo na linha da chave.
É 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."
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.
Última atualização