Saltar para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.


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 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.


The Create API Key dialog with the name, expiry and the scrollable list of read and write scopes

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.

Â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.

Última atualização