Tokens de API

Os tokens de API dão aos seus sistemas externos e scripts acesso seguro e com âmbito definido à plataforma Mirox sem partilhar as suas credenciais de início de sessão. Cria-os no seu perfil, atribui a cada um apenas as permissões de que necessita e pode revogar ou rodar qualquer um deles a qualquer momento.

Visão geral

Ao contrário do seu nome de utilizador e palavra-passe, um token de API:

Possui um grupo de permissões específico que limita o que pode alcançar
Tem uma data de expiração configurável (por predefinição um ano, máximo cinco anos)
Pode ser rodado para um novo segredo ou revogado individualmente, sem afetar a sua conta ou os seus outros tokens
Regista o seu próprio histórico de utilização (hora da última utilização, IP de origem, localização, navegador e sistema operativo) para que possa ver como cada integração se está a comportar

Pode ter até 64 tokens em simultâneo.

Criar tokens de API

Os tokens de API podem ser criados através da interface web do Mirox:

Inicie sessão na sua conta Mirox
Abra o menu Perfil (canto superior direito) e escolha Perfil
Selecione o separador "Tokens de API"
Clique em "Criar novo token"
Configure as definições do token:
- Nome (etiqueta descritiva do token)
- Data de expiração (predefinida para 1 ano se não for especificada, máximo 5 anos)
- Âmbito de permissões (recursos e ações específicos a que o token pode aceder)
Clique em "Gerar token"

Abrir no Mirox: Perfil ▸ Tokens de API — gira os seus tokens a partir do menu Perfil ▸ Perfil e, em seguida, do separador "Tokens de API".

Guarde o seu token imediatamente

Copie e armazene o token de forma segura — só será apresentado uma vez. Se perder o token, terá de o rodar ou criar um novo.

Os tokens são criados a partir de uma sessão de navegador

Criar e rodar tokens requer uma sessão web ativa e com sessão iniciada. Um token não pode ser utilizado para criar ou rodar outros tokens, pelo que um token de API existente, por si só, não pode gerir o seu conjunto de tokens.

Tokens, 2FA e regras de início de sessão

Um token de API destina-se à automatização. Nunca lhe é pedido um segundo fator, e não é terminado pela duração do início de sessão que a sua organização define. Funciona até à sua própria data de expiração, ou até o revogar ou rodar. Aplica-se uma regra quando cria um token: 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, com uma aplicação de autenticação ou uma passkey. Os tokens que já existem continuam a funcionar. Consulte Política de Segurança da Organização.

Boas práticas de segurança para tokens

Ao trabalhar com tokens de API:

Armazene de forma segura — Trate os tokens como palavras-passe; nunca os codifique de forma fixa nas aplicações
Utilize variáveis de ambiente — Armazene os tokens em variáveis de ambiente ou em cofres de credenciais seguros
Limite o âmbito — Crie tokens com as permissões mínimas necessárias para a integração
Defina expirações adequadas — Utilize períodos de expiração mais curtos para integrações temporárias
Planeie a rotação — Defina lembretes no calendário antes da expiração do token para garantir a continuidade do serviço
Rode regularmente — Utilize a ação integrada Rodar para alternar o segredo de um token periodicamente antes da sua expiração, especialmente em sistemas de produção
Revogue os não utilizados — Revogue imediatamente os tokens que já não são necessários
Monitorize a utilização — Audite regularmente a atividade dos tokens através da interface do Mirox

Aviso

Os tokens expiram na data configurada e todas as integrações que utilizam esse token deixarão de funcionar imediatamente.

Utilizar tokens de API

Os tokens de API são utilizados em pedidos HTTP como um token Bearer no cabeçalho Authorization:

Authorization: Bearer your-api-token

Os exemplos seguintes requerem um token no grupo de permissões Full Access.

Exemplo de pedido HTTP

GET /api/v1/park HTTP/1.1
Host: service.mirox.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Exemplo com Curl

curl -X GET \
  https://service.mirox.io/api/v1/park \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Permissões dos tokens

Os tokens de API estão sujeitos à Camada de permissões de tokens de API da plataforma Mirox. Pontos-chave sobre as permissões dos tokens:

Os tokens herdam as permissões do utilizador que os criou (nunca mais do que isso)
As permissões podem ser ainda mais restringidas por funcionalidade
Os tokens operam dentro do mesmo modelo de permissões hierárquico que as contas de utilizador
Todos os controlos de segurança da plataforma se aplicam ao acesso baseado em tokens

Para informações detalhadas sobre como os tokens de API se enquadram na arquitetura global de permissões, consulte a documentação do Sistema de permissões.

Grupos de permissões

Ao criar um token, escolhe um de três grupos de permissões que definem o âmbito do que ele pode alcançar:

Full Access — concede ao token as mesmas permissões que a sua conta de utilizador, dentro do seu âmbito. Qualquer serviço que o utilize pode atuar em seu nome em toda a plataforma, por isso só deve escolher esta opção quando uma integração necessitar genuinamente de acesso alargado.
Metric Export — restringe o token à leitura da 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. É o grupo para o Excel, as ferramentas de BI e os scripts de exportação.
Timeseries Database — restringe o token aos endpoints de consulta de séries temporais, para ler as séries de medição em bruto.

Escolha o grupo mais restrito que cubra a sua integração. Um token Metric Export ou Timeseries Database não consegue alcançar nada fora do seu âmbito, o que limita o raio de impacto caso alguma vez seja exposto.

O grupo chamava-se Reporting

Os tokens que criou no grupo Reporting são agora tokens Metric Export. Continuam a funcionar e leem as mesmas ligações de antes e, além disso, todas as ligações da exportação de métricas e da exportação legada bruta e de componentes. Os relatórios que o próprio Mirox gera não são acionados por tokens de API.

Na página Exportação de dados, Experimentar, junto a uma ligação de exportação, cria um token Metric Export num só passo — consulte Exportação de métricas.

Gestão do ciclo de vida dos tokens

Monitorizar a utilização dos tokens

Acompanhe a atividade dos tokens de API através de:

A secção "Tokens de API" no seu perfil
Os registos de auditoria que mostram quando e como cada token foi utilizado

Rodar tokens

A rotação substitui o segredo de um token sem alterar o seu nome, grupo de permissões ou posição na sua lista de tokens. Isto permite-lhe alternar uma chave de forma programada, ou reagir a uma suspeita de fuga, mantendo a mesma entrada de token na configuração das suas integrações.

Para rodar um token:

Navegue até à secção "Tokens de API" no seu perfil
Encontre o token na lista e escolha "Rodar"
Copie o novo segredo imediatamente — só é apresentado uma vez
Atualize o segredo na integração que o utiliza

A rotação emite um novo segredo, repõe a janela de expiração e limpa o histórico de utilização registado do token. O segredo antigo deixa de funcionar imediatamente, por isso atualize as suas integrações como parte da rotação.

Planeie a rotação para janelas de inatividade

Como o segredo anterior é invalidado no momento em que roda, qualquer integração que ainda utilize o valor antigo começará a falhar. Rode durante uma janela de manutenção, ou esteja preparado para atualizar de imediato o sistema que o consome.

Revogar tokens

Para revogar um token:

Navegue até à secção "Tokens de API" no seu perfil
Encontre o token na lista
Clique em "Revogar"
Confirme a ação

A revogação tem efeito imediato e quaisquer pedidos subsequentes que utilizem o token falharão.

Limitações de utilização

Os tokens de API estão sujeitos aos mesmos limites de taxa que as contas de utilizador normais. Para detalhes sobre estas limitações, consulte a secção Limitação de taxa na documentação dos Conceitos de autenticação.

Resolução de problemas

Problemas comuns com tokens e respetivas soluções:

Problema	Causa possível	Solução
401 Unauthorized	Token inválido, revogado, rodado ou expirado	Verifique a validade do token, ou rode / crie um novo
403 Forbidden	O grupo de permissões do token não cobre o endpoint solicitado	Utilize um token num grupo de permissões que conceda o acesso, ou um no grupo Full Access
429 Too Many Requests	Limite de taxa excedido	Abrande e implemente uma estratégia de recuo exponencial
Não é possível criar um novo token	A sua organização exige 2FA e a sua conta não tem segundo fator	Ative o 2FA no seu perfil (aplicação de autenticação ou passkey) e depois crie o token. Os tokens existentes não são afetados

Exemplos de código

Para código funcional que utiliza um token de API de ponta a ponta, consulte:

Gerador externo de relatórios — um script Python que se autentica com um token e lê um modelo de exportação
Exportação de métricas para Excel — ligações de exportação prontas a usar, e o Power Query do Excel com o token no cabeçalho Authorization

Dica

Os endpoints e parâmetros exatos podem mudar ao longo do tempo. A referência atual e autoritativa é sempre a documentação OpenAPI em /docs.

Funcionalidades relacionadas

Visão geral da API — o ponto de entrada para a API REST do Mirox e a sua documentação em tempo real
Sistema de permissões — como os grupos de permissões de tokens se enquadram no modelo de funções da plataforma
Autenticação — sessões, início de sessão com dois fatores e os limites de taxa que também se aplicam aos tokens
Exportação de métricas — exporte métricas como séries temporais com um token Metric Export
API de exportação de métricas — os parâmetros das ligações de exportação