> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metricaas.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Bearer token, modos de acesso e por que a permissão pode mudar sozinha.

Toda chamada leva o token no header:

```bash theme={null}
curl https://app.metricaas.com.br/v1/me \
  -H "Authorization: Bearer mcp_SEU_TOKEN"
```

## Gerar o token

Em **Configurações → Tokens de API**, escolha:

| Campo        | O que significa                                                                  |
| ------------ | -------------------------------------------------------------------------------- |
| **Modo**     | `read` responde `403` a qualquer verbo que não seja `GET`. `write` lê e escreve. |
| **Herda de** | A pessoa cujo papel o token carrega. O token nunca alcança mais que ela.         |
| **Validade** | O token expira. Sem prorrogação automática — é de propósito.                     |

<Warning>
  O valor aparece **uma única vez**. O banco guarda só o hash: não há tela de "ver
  token de novo". Perdeu, gera outro e revoga o antigo.
</Warning>

## As permissões do token mudam sozinhas — e isso é o desenho

As capacidades efetivas são a **interseção** entre o que o token pede e o que a
pessoa tem *neste momento*. O papel é lido a cada chamada, não no dia da emissão.

Consequências práticas:

* Se essa pessoa perder uma permissão na grade de Equipe, **o token perde junto** —
  sem ninguém lembrar de revogar.
* Se ela sair da empresa, o token para de funcionar na hora.
* Um token **nunca concede** o que a pessoa não tem. Não existe escalada por token.

## Escopo de dados: a resposta pode estar incompleta sem erro nenhum

Além das capacidades, a pessoa pode ter **escopos** que limitam quais leads ela
enxerga — por canal, por origem, ou "só os meus". O token herda isso.

Um token emitido sobre alguém com `channels: ["whatsapp"]` **não vê lead do
Instagram**. A API responde `200`, a lista vem certinha, e os totais estão menores
do que a empresa realmente tem. Não há aviso, porque do ponto de vista do token
aqueles leads não existem.

<Tip>
  Sempre que um número não bater, chame `GET /v1/me` e olhe `scopes` e
  `sees_all_leads` antes de qualquer outra coisa. É a causa mais comum.
</Tip>

```json theme={null}
{
  "token": { "id": "…", "mode": "write" },
  "client": { "name": "Minha Empresa", "slug": "minha-empresa" },
  "role": "manager",
  "sees_all_leads": true,
  "scopes": { "channels": ["whatsapp"] },
  "capabilities": ["crm:operate", "funil:view", "leads:view", "..."]
}
```

## Erros de autenticação

Todos vêm como `401` com o motivo em `detail` — inválido, expirado e revogado são
mensagens diferentes, para você saber se o problema é a variável de ambiente ou a
tela de tokens.