> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrito.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OAuth 2.0
> Permita que plataformas de terceiros se conectem a workspaces do Metrito com consentimento do usuário
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 Metrito
Ao 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
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.
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`.
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.
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.
```bash theme={null}
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
```json theme={null}
{
"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
```json theme={null}
{
"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:
```bash theme={null}
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
O código de autorização (`code`) expira em 5 minutos e é invalidado imediatamente após o primeiro uso. Não pode ser reutilizado.
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.
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.
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:
Envie um e-mail para **[contato@metrito.com](mailto: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.