Autenticação

O Metrito oferece diferentes métodos de autenticação dependendo da API e do caso de uso.

Métodos de Autenticação

API Key (Recomendado)

Chave de serviço com escopos granulares. Ideal para integrações, automações e acesso programático.

JWT Token

Token obtido via login com e-mail e senha. Usado para integrações que precisam de contexto de usuário.

OAuth 2.0

Para plataformas de terceiros que precisam conectar workspaces de usuários sem intervenção manual. Gera uma API Key automaticamente com consentimento do usuário.

API Key (Chave de Serviço)

API Keys são a forma recomendada de autenticação para integrações. Têm escopos granulares, não expiram (a menos que configurado) e não dependem de sessão de usuário.

Formato

Todas as API Keys seguem o formato mtk_live_... e podem ser enviadas de duas formas:

# Via header Authorization
curl -X POST https://api.metrito.com/v3/query \
  -H "Authorization: Bearer mtk_live_abc123..."

# Via header x-api-key
curl -X POST https://api.metrito.com/v3/query \
  -H "x-api-key: mtk_live_abc123..."

Ao usar API Key, não é necessário enviar o header X-Workspace-Id — o workspace é resolvido automaticamente pela chave.

Como criar uma API Key

Acesse as Configurações

Na plataforma Metrito, clique no menu lateral e acesse Configurações (ícone de engrenagem).

Vá até Chaves de API

Na página de configurações, selecione a aba Chaves de API.

Crie uma nova chave

Clique em Criar chave de API e preencha:

Nome: identificador para referência (ex: “n8n Produção”, “Meu Dashboard”)
Escopos: permissões que a chave terá
Expiração: nunca, 30 dias, 90 dias ou 1 ano

Copie o token

Após a criação, copie o token imediatamente. Ele não será exibido novamente por segurança.

Escopos Disponíveis

Escopo	Descrição
`tracking:read`	Leitura de containers, eventos, decode messages (`GET /v3/tracking/*`)
`tracking:write`	Enviar eventos de rastreamento, criar/editar conversões (`POST /v3/tracking/*`)
`data:read`	Consultar métricas via Data API (`POST /v3/query`, `GET /v3/fields`, `GET /v3/connections/*`)
`data:write`	Escrita de dados na Data API (reservado para uso futuro)

Selecione apenas os escopos necessários para sua integração. Chaves com menos permissões são mais seguras.

Para obter um JWT, use o endpoint de login:

curl -X POST https://api.metrito.com/v3/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "seu@email.com", "password": "suaSenha" }'

A resposta contém o token JWT:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "60f1b2c3d4e5f6a7b8c9d0e1",
    "name": "João Silva",
    "email": "seu@email.com",
    "role": "owner"
  }
}

Use o token nas requisições autenticadas:

curl -X GET https://api.metrito.com/v3/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

O JWT expira em 7 dias. Para integrações de longa duração, use API Keys.

Resumo por API

API	Endpoint	Autenticação
Plataforma	`POST /v3/auth/login`	Nenhuma (retorna JWT)
Plataforma	`GET /v3/projects`	JWT ou API Key (`data:read`)
Plataforma	`GET /v3/projects/{id}/connections`	JWT ou API Key (`data:read`)
Plataforma	`GET /v3/connections/{id}/sync`	JWT ou API Key (`data:read`)
Plataforma	`PUT /v3/connections/{id}/objects`	JWT ou API Key (`data:write`)
Rastreamento	`GET /v3/tracking/containers/{id}`	API Key (`tracking:read`)
Rastreamento	`GET /v3/tracking/containers/{id}/triggers`	API Key (`tracking:read`)
Rastreamento	`POST /v3/tracking/containers/{id}/triggers`	API Key (`tracking:write`)
Rastreamento	`PUT/DELETE /v3/tracking/containers/{id}/triggers/{triggerId}`	API Key (`tracking:write`)
Rastreamento	`POST /v3/tracking/events`	API Key ou Nenhuma (dual-mode)
Rastreamento	`POST /v3/tracking/messages/decode`	API Key (`tracking:read`)
Rastreamento	`POST /v2/tracking/generic?k={chave}`	Query param `k`
Dados	`GET /v3/fields`	JWT + `X-Workspace-Id` ou API Key (`data:read`)
Dados	`POST /v3/query`	JWT + `X-Workspace-Id` ou API Key

Visão Geral

Plataforma

API de Dados

API de Rastreamento

Métodos de Autenticação

API Key (Recomendado)

JWT Token

OAuth 2.0

API Key (Chave de Serviço)

Formato

Como criar uma API Key

Escopos Disponíveis

Resumo por API

​Métodos de Autenticação

API Key (Recomendado)

JWT Token

OAuth 2.0

​API Key (Chave de Serviço)

​Formato

​Como criar uma API Key

​Escopos Disponíveis

​JWT Token (Login)

​Resumo por API

Métodos de Autenticação

API Key (Chave de Serviço)

Formato

Como criar uma API Key

Escopos Disponíveis

JWT Token (Login)

Resumo por API