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:

1. Inicie sessão na sua conta Mirox
2. Abra o menu Perfil (canto superior direito) e escolha Perfil
3. Selecione o separador "Tokens de API"
4. Clique em "Criar novo token"
5. 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)
6. 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".

Boas práticas de segurança para tokens

Ao trabalhar com tokens de API:

1. Armazene de forma segura — Trate os tokens como palavras-passe; nunca os codifique de forma fixa nas aplicações
2. Utilize variáveis de ambiente — Armazene os tokens em variáveis de ambiente ou em cofres de credenciais seguros
3. Limite o âmbito — Crie tokens com as permissões mínimas necessárias para a integração
4. Defina expirações adequadas — Utilize períodos de expiração mais curtos para integrações temporárias
5. Planeie a rotação — Defina lembretes no calendário antes da expiração do token para garantir a continuidade do serviço
6. 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
7. Revogue os não utilizados — Revogue imediatamente os tokens que já não são necessários
8. Monitorize a utilização — Audite regularmente a atividade dos tokens através da interface do Mirox

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.
• Reporting — restringe o token às funcionalidades de relatórios: gerar relatórios e exportar dados.
• Timeseries Database — restringe o token aos endpoints de consulta de séries temporais, para obter dados de medição de forma programática (por exemplo, com o MiroxQL).

Escolha o grupo mais restrito que cubra a sua integração. Um token Reporting 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.

Gestão do ciclo de vida dos tokens

Monitorizar a utilização dos tokens

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

1. A secção "Tokens de API" no seu perfil
2. 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:

1. Navegue até à secção "Tokens de API" no seu perfil
2. Encontre o token na lista e escolha "Rodar"
3. Copie o novo segredo imediatamente — só é apresentado uma vez
4. 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.

Revogar tokens

Para revogar um token:

1. Navegue até à secção "Tokens de API" no seu perfil
2. Encontre o token na lista
3. Clique em "Revogar"
4. 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:

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 obtém uma exportação de métricas
• MiroxQL — a linguagem de consulta para obter dados de séries temporais com um token Timeseries Database

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
• MiroxQL — consulte dados de séries temporais de forma programática com um token Timeseries Database
• API de exportação de métricas — exporte dados de medição e relatórios com um token Reporting