Skip to main content
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

1

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.
2

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.
3

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.
4

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âmetroObrigatórioDescrição
client_idSimIdentificador da sua plataforma, fornecido pelo time do Metrito (ex: metrito_app_suaplataforma)
redirect_uriSimURL para onde o usuário será redirecionado após a autorização. Deve corresponder exatamente à URI registrada pelo time do Metrito
stateSimString 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"
}
CampoObrigatórioDescrição
grant_typeSimDeve ser "authorization_code"
client_idSimSeu identificador de aplicativo OAuth
client_secretSimSeu segredo de aplicativo OAuth. Nunca exponha isso no frontend
codeSimO código recebido no redirecionamento
redirect_uriSimExatamente a mesma URI usada na etapa de autorização
key_nameNãoNome 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
}
CampoDescrição
access_tokenA API Key do Metrito no formato mtk_live_.... Use como Bearer token em todas as chamadas da API
token_typeSempre "bearer"
scopeEscopos concedidos (sempre todos os quatro escopos disponíveis)
workspace_idID da workspace que o usuário autorizou
key_nameNome da chave criada na workspace
expires_atData 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.
EscopoPermissão
tracking:readLeitura de containers, eventos e decode messages
tracking:writeEnvio de eventos de rastreamento e criação de conversões
data:readConsulta de métricas de anúncios via Data API
data:writeEscrita 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 HTTPMensagemCausa
400redirect_uri is not registeredA URI não foi registrada para este client_id
400Invalid authorization codeCódigo inválido, expirado ou já utilizado
400client_id mismatchO client_id na troca não corresponde ao usado na autorização
400redirect_uri mismatchA redirect_uri na troca difere da usada na autorização
401Invalid client credentialsclient_id ou client_secret incorretos
404OAuth application not foundclient_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.