OAuth 2.0

O Metrito suporta um fluxo de autorização baseado em OAuth 2.0 Authorization Code para plataformas de terceiros — como ferramentas de automação, CRMs e plataformas de marketing — que precisam acessar workspaces do Metrito em nome de seus usuários. Com esse fluxo, o usuário nunca precisa criar ou copiar uma API Key manualmente. A plataforma parceira redireciona o usuário para o Metrito, onde ele visualiza uma tela de consentimento, seleciona a workspace e aprova o acesso. O resultado é uma API Key criada automaticamente, pronta para uso.

O client_id e o client_secret não são gerados automaticamente. Para integrar sua plataforma com o Metrito via OAuth, você precisa solicitá-los diretamente com a equipe do Metrito.→ Entrar em contato com o time do MetritoAo entrar em contato, informe o nome da sua plataforma, a URL de redirecionamento (redirect_uri) que você usará e uma breve descrição do caso de uso.

Como funciona o fluxo

Redirecionar o usuário para a tela de consentimento

Sua plataforma redireciona o usuário para a URL de autorização do Metrito. O usuário precisa estar logado no Metrito — caso não esteja, será redirecionado automaticamente para o login antes de ver a tela de consentimento.

https://app.metrito.com/authorize
  ?client_id=metrito_app_suaplataforma
  &redirect_uri=https://suaplataforma.com/metrito/callback
  &state=TOKEN_CSRF_GERADO_POR_VOCE

O parâmetro state deve ser um valor aleatório gerado pela sua plataforma para prevenir ataques CSRF. Você receberá ele de volta no redirecionamento.

Usuário aprova o acesso

O Metrito exibe uma tela mostrando o nome da sua plataforma, as permissões que serão concedidas e um seletor de workspace. O usuário seleciona a workspace que deseja conectar e clica em Autorizar acesso.Se o usuário clicar em Cancelar, será redirecionado para a redirect_uri com error=access_denied.

Metrito redireciona de volta com um código

Após a aprovação, o Metrito redireciona para a redirect_uri registrada com um código de autorização de uso único:

https://suaplataforma.com/metrito/callback
  ?code=CODIGO_DE_AUTORIZACAO
  &state=TOKEN_CSRF_GERADO_POR_VOCE

Valide que o state recebido corresponde ao que você enviou. O code expira em 5 minutos e só pode ser usado uma vez.

Trocar o código por uma API Key (servidor para servidor)

No backend da sua plataforma, troque o código por uma API Key do Metrito. Essa chamada usa o client_secret e nunca deve ser feita pelo frontend.

curl -X POST https://api.metrito.com/v3/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "metrito_app_suaplataforma",
    "client_secret": "sk_live_...",
    "code": "CODIGO_DE_AUTORIZACAO",
    "redirect_uri": "https://suaplataforma.com/metrito/callback",
    "key_name": "Sua Plataforma"
  }'

A API Key retornada (access_token) pode ser usada imediatamente para autenticar chamadas à API do Metrito.

URL de Autorização

https://app.metrito.com/authorize

Parâmetros

Parâmetro	Obrigatório	Descrição
`client_id`	Sim	Identificador da sua plataforma, fornecido pelo time do Metrito (ex: `metrito_app_suaplataforma`)
`redirect_uri`	Sim	URL para onde o usuário será redirecionado após a autorização. Deve corresponder exatamente à URI registrada pelo time do Metrito
`state`	Sim	String aleatória gerada pela sua plataforma para prevenção de CSRF. Será retornada no redirecionamento

Troca de Código por API Key

Endpoint

POST https://api.metrito.com/v3/oauth/token

Body da requisição

{
  "grant_type": "authorization_code",
  "client_id": "metrito_app_suaplataforma",
  "client_secret": "sk_live_...",
  "code": "CODIGO_DE_AUTORIZACAO",
  "redirect_uri": "https://suaplataforma.com/metrito/callback",
  "key_name": "Sua Plataforma - Conta do João"
}

Campo	Obrigatório	Descrição
`grant_type`	Sim	Deve ser `"authorization_code"`
`client_id`	Sim	Seu identificador de aplicativo OAuth
`client_secret`	Sim	Seu segredo de aplicativo OAuth. Nunca exponha isso no frontend
`code`	Sim	O código recebido no redirecionamento
`redirect_uri`	Sim	Exatamente a mesma URI usada na etapa de autorização
`key_name`	Não	Nome da chave que aparecerá na workspace do usuário. Se omitido, usa o nome da sua plataforma (ex: `"Zapflow"`)

Resposta

{
  "access_token": "mtk_live_AbCdEfGh...",
  "token_type": "bearer",
  "scope": "tracking:read tracking:write data:read data:write",
  "workspace_id": "60f1b2c3d4e5f6a7b8c9d0e1",
  "key_name": "Sua Plataforma - Conta do João",
  "expires_at": null
}

Campo	Descrição
`access_token`	A API Key do Metrito no formato `mtk_live_...`. Use como `Bearer` token em todas as chamadas da API
`token_type`	Sempre `"bearer"`
`scope`	Escopos concedidos (sempre todos os quatro escopos disponíveis)
`workspace_id`	ID da workspace que o usuário autorizou
`key_name`	Nome da chave criada na workspace
`expires_at`	Data de expiração da chave, ou `null` se não expira

Usando a API Key

Após receber o access_token, use-o como Bearer token em todas as chamadas:

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

A API Key criada via OAuth fica visível na seção Configurações → Chaves de API da workspace do usuário, identificada com o nome da sua plataforma. O usuário pode revogá-la a qualquer momento.

Escopos

Toda API Key gerada via OAuth recebe automaticamente todos os escopos disponíveis. Não há seleção de escopos por parte da plataforma parceira ou do usuário.

Escopo	Permissão
`tracking:read`	Leitura de containers, eventos e decode messages
`tracking:write`	Envio de eventos de rastreamento e criação de conversões
`data:read`	Consulta de métricas de anúncios via Data API
`data:write`	Escrita de dados na Data API

Segurança

Códigos de uso único

O código de autorização (code) expira em 5 minutos e é invalidado imediatamente após o primeiro uso. Não pode ser reutilizado.

Proteção contra CSRF

O parâmetro state é retornado intacto no redirecionamento. Sempre valide que o valor recebido corresponde ao que você enviou antes de trocar o código.

redirect_uri obrigatória

A redirect_uri usada na troca de código deve ser idêntica à registrada e à utilizada na autorização. URIs não registradas são rejeitadas.

client_secret no servidor

O client_secret só deve existir no backend da sua plataforma. Nunca inclua-o em código de frontend, aplicativos móveis ou em URLs.

Erros comuns

Código HTTP	Mensagem	Causa
`400`	`redirect_uri is not registered`	A URI não foi registrada para este `client_id`
`400`	`Invalid authorization code`	Código inválido, expirado ou já utilizado
`400`	`client_id mismatch`	O `client_id` na troca não corresponde ao usado na autorização
`400`	`redirect_uri mismatch`	A `redirect_uri` na troca difere da usada na autorização
`401`	`Invalid client credentials`	`client_id` ou `client_secret` incorretos
`404`	`OAuth application not found`	`client_id` não existe ou foi revogado

Solicitar credenciais

Para integrar sua plataforma ao Metrito via OAuth, entre em contato com nosso time:

Solicitar client_id e client_secret

Envie um e-mail para contato@metrito.com com o nome da sua plataforma, a redirect_uri que você usará e uma breve descrição do caso de uso. O time do Metrito retornará suas credenciais em até 2 dias úteis.

Visão Geral

Plataforma

API de Dados

API de Rastreamento

Como funciona o fluxo

URL de Autorização

Parâmetros

Troca de Código por API Key

Endpoint

Body da requisição

Resposta

Usando a API Key

Escopos

Segurança

Códigos de uso único

Proteção contra CSRF

redirect_uri obrigatória

client_secret no servidor

Erros comuns

Solicitar credenciais

Solicitar client_id e client_secret

​Como funciona o fluxo

​URL de Autorização

​Parâmetros

​Troca de Código por API Key

​Endpoint

​Body da requisição

​Resposta

​Usando a API Key

​Escopos

​Segurança

Códigos de uso único

Proteção contra CSRF

redirect_uri obrigatória

client_secret no servidor

​Erros comuns

​Solicitar credenciais

Solicitar client_id e client_secret

Como funciona o fluxo

URL de Autorização

Parâmetros

Troca de Código por API Key

Endpoint

Body da requisição

Resposta

Usando a API Key

Escopos

Segurança

Erros comuns

Solicitar credenciais