Tokens de API

Os tokens de API permitem ligar sistemas externos, scripts e ferramentas à plataforma Mirox com credenciais delimitadas e revogáveis que nunca expõem a sua palavra-passe. Cada token autentica pedidos máquina-a-máquina em seu nome, para que possa exportar métricas e automatizar as suas integrações sem partilhar o seu início de sessão.

Conceito de Token

Cada token pertence ao utilizador que o criou e comporta-se como esse utilizador, dentro de limites:

  • Associado à sua conta — um token atua em seu nome e tudo o que faz é-lhe atribuído no rasto de auditoria.
  • Teto de permissões — um token nunca pode alcançar nada que o próprio utilizador não consiga alcançar. A sua função e o seu acesso a recursos limitam sempre o que o token vê.
  • Delimitado por grupo de permissões — escolhe um grupo de permissões no momento da criação para restringir ainda mais o token (ver abaixo).
  • Mostrado uma única vez — o valor completo do token é apresentado uma única vez quando o cria. Guarde-o de forma segura; a Mirox mantém apenas uma cópia em hash e nunca o poderá mostrar novamente.
  • Feito para a automatização — nunca é pedido um segundo fator a um token, e ele não é terminado pelas regras de início de sessão da sua organização. Consulte Tokens e Autenticação de Dois Fatores.

Isto mantém a automatização responsável: mesmo que um token seja comprometido, está limitado a um único âmbito, é fácil de revogar e está isolado dos seus restantes tokens.

Grupos de Permissões

Ao criar um token, escolhe um grupo de permissões que define o que ele pode fazer:

GrupoO que o token pode fazer
Full AccessAtua com o seu acesso completo — todas as superfícies de API que consegue alcançar.
Metric ExportLer apenas a exportação de dados: métricas como séries temporais, modelos de exportação, o catálogo de métricas, informações da central e eventos. Não pode alterar nada.
Timeseries DatabaseLer apenas as séries de medição em bruto.

Um grupo nunca alarga o seu acesso; apenas restringe o token em relação às suas próprias permissões. Para a definição completa de cada grupo, consulte a secção grupos de permissões de API da documentação do sistema de permissões.

Adeque o grupo à tarefa

Atribua a cada integração o grupo mais restrito que ainda funcione. Um livro ou um script que lê exportações precisa apenas de Metric Export; um cliente que lê as séries de medição em bruto precisa apenas de Timeseries Database. Isto limita o raio de impacto caso um token seja comprometido.

Criar e Gerir Tokens

Gere os seus tokens a partir do seu perfil. A plataforma cobre todo o ciclo de vida:

Criar um Token

  • Nome e descrição — uma etiqueta clara e uma nota para que se lembre da finalidade de cada token.
  • Grupo de permissões — escolha um dos grupos acima.
  • Expiração — opcional. Os tokens têm por predefinição um período de validade de um ano, podendo definir qualquer data de expiração até um máximo de cinco anos.
  • Revelação única — o token completo é mostrado uma única vez na criação e nunca mais.

Pode ter até 64 tokens ativos por conta.

Criar e rodar no navegador

Os tokens criam-se e rodam-se no navegador, com sessão iniciada na Mirox. Não pode usar um token de API para criar ou rodar outro — isto impede que um token comprometido crie discretamente mais tokens.

Rodar um Token

A rotação substitui o segredo de um token no local, sem alterar o seu nome, descrição ou grupo de permissões:

  • É emitido um novo segredo, mostrado uma única vez.
  • O segredo antigo deixa de funcionar imediatamente.
  • A expiração é reposta e o histórico de utilização é limpo.

A rotação é a forma recomendada de renovar integrações de longa duração de forma periódica, ou de responder a uma suspeita de comprometimento, sem reconfigurar qual integração usa qual token.

Monitorizar e Revogar

  • Inventário — liste todos os seus tokens com o respetivo nome, grupo de permissões e datas de criação e expiração.
  • Informação de utilização — veja quando cada token foi usado pela última vez, juntamente com o IP, localização, navegador e sistema operativo captados nesse momento. O valor do token em si nunca volta a ser mostrado.
  • Revogação imediata — elimine um token para o invalidar instantaneamente. Revogar um token nunca afeta os restantes.

Tokens e Autenticação de Dois Fatores

Um token de API destina-se a scripts e integrações que correm sem uma pessoa ao teclado. Por isso, as regras de início de sessão para pessoas não se lhe aplicam:

  • Sem segundo fator. Nunca é pedido um código a um token, tenha ou não a sua conta autenticação de dois fatores (2FA).
  • Não é terminado pelas regras de início de sessão. A sua organização pode definir quanto tempo dura um início de sessão na aplicação web e na aplicação móvel. Um token não é um início de sessão: continua a funcionar até à sua própria data de expiração, ou até o rodar ou revogar. Ficar com a sessão terminada não para os seus tokens.
  • Não é alterado por uma exigência de 2FA. Quando uma organização exige 2FA para aceder às centrais, essa regra aplica-se às pessoas com sessão iniciada na aplicação web e na aplicação móvel. Não altera aquilo que um token existente consegue alcançar.

Há uma regra que se aplica: enquanto a sua própria organização exigir 2FA e a sua conta não tiver segundo fator, não pode criar um novo token. Ative primeiro o 2FA (aplicação de autenticação ou passkey) — consulte Autenticação de Dois Fatores. Entretanto, os seus tokens existentes continuam a funcionar.

Como um token não está protegido por um segundo fator, trate-o como uma palavra-passe: guarde-o em segurança, dê-lhe o grupo de permissões mais restrito, defina uma expiração e revogue-o quando já não for necessário. Para as regras da organização, consulte Política de Segurança da Organização.

Casos de Uso Comuns

Os tokens de API suportam uma vasta gama de cenários de integração.

Metric Export

Um token Metric Export lê todas as ligações da exportação de métricas e da exportação legada:

  • Atualize livros do Excel e dashboards de BI a partir de uma ligação de exportação.
  • Alimente armazéns de dados e pipelines de análise com dados de produção e de desempenho.
  • Crie os seus próprios relatórios a partir de dados exportados.

O token não pode criar nem alterar modelos, métricas ou qualquer outra coisa. Os relatórios que o próprio Mirox gera não são acionados por tokens de API: são gerados, publicados e transferidos na aplicação.

Acesso a Métricas de Séries Temporais

  • Leia as séries de medição em bruto das suas centrais, as mesmas séries que o Grafana lê.
  • Ligue ferramentas de análise só de leitura que usem a linguagem de consulta do armazenamento de séries temporais.

Segurança e Controlo

  • Isolamento de tokens — um token comprometido nunca expõe a sua palavra-passe nem os seus restantes tokens.
  • Rotação agendada — rode tokens de longa duração periodicamente através da ação de rotação, mantendo a mesma configuração.
  • Validade temporal — defina uma expiração para que tokens abandonados caduquem automaticamente.
  • Atribuição completa — todas as ações que um token realiza são registadas em seu nome, mantendo a utilização responsável e auditável.

Funcionalidades Relacionadas