Autenticação

Todo acesso à API e ao MCP é de uma pessoa. Não existe chave da empresa nem token sem dono: cada pessoa cria e revoga os próprios tokens, e o token age com exatamente as permissões e a visibilidade dela no app. Quando a pessoa sai, o acesso sai junto.

Authorization: Bearer nexo_pat_seu_token

Tokens pessoais

Criar

No Nexo, Configurações → Tokens de API, com a sua sessão no app:

Campo	Regra
Nome	1 a 80 caracteres, para reconhecer o token na lista
Escopos	Pelo menos um. Padrão: `context:read`, `conversations:read` e `exports:create`. Escopo de escrita só quando você marca
Validade	30, 90 (padrão) ou 365 dias. Todo token expira

O token completo (nexo_pat_ + 32 caracteres + 6 de verificação) só aparece na resposta da criação. O Nexo guarda apenas um hash, o começo do token e os 4 últimos caracteres, que a lista mostra junto com escopos, validade, situação (active, expired, revoked) e último uso (atualizado no máximo a cada 5 minutos).

Regras da criação:

No máximo 20 tokens válidos por pessoa. O 21º recebe 409 public_api.too_many_tokens: revogue um antes.
Token não cria token. Criar e revogar só existe no app, com a sessão da própria pessoa (a tela usa as rotas GET, POST e DELETE /api-tokens do app, não a API pública).
Só a própria pessoa. O modo de visita (o administrador entrando como outra pessoa) e a administração da plataforma não criam tokens (403 public_api.tokens_unavailable).

Escopos

Escopo	O que libera
`context:read`	Contexto da empresa, negócios, indicadores, metas, tarefas, relatórios, revisão, Calibração e Base de conhecimento (leitura)
`conversations:read`	Conversas na íntegra: listas, leituras, trechos, transcrições, arquivos e downloads
`exports:create`	Exportações. Exportar conversas exige também `conversations:read`
`calibration:write`	Mudar a Calibração e a Base de conhecimento dela. Só vale para administradores
`deals:write`	Registrar o próximo passo de um negócio e escrevê-lo no CRM, com a mesma visibilidade de negócios do app

GET /v1/me não exige escopo nenhum. O escopo de cada rota e de cada ferramenta está na Referência da API e na Referência do MCP.

Papéis e visibilidade

A permissão efetiva é papel ∩ escopos ∩ plano: o token nunca faz mais do que a pessoa faria no app.

Papel (`role`)	O que enxerga
`admin`	Tudo da empresa, inclusive a Calibração, a Base de conhecimento, a atividade da API e a exportação da empresa inteira
`sales_lead`	Os negócios, as conversas, os indicadores e as metas da empresa; a Calibração e a Base de conhecimento são só de administrador
`rep` (vendedor)	Os próprios negócios e conversas

O papel é relido a cada requisição: rebaixar alguém estreita o token na hora. Fora do papel, a resposta é 403 public_api.role_not_allowed; sem o escopo, 403 public_api.insufficient_scope com o escopo que faltou em meta.scope.

Revogar e expirar

Você revoga um token em Configurações → Tokens de API, e ele deixa de valer na hora.
A pessoa foi inativada ou removida (pelo administrador ou pelo CRM): os tokens dela param no mesmo instante e são revogados de vez. Reativar a pessoa não ressuscita token antigo; ela cria outro.
Expirou: o token passa a responder 401. Crie outro.

O administrador não lista nem revoga token de outra pessoa. O que ele tem é a atividade (GET /v1/activity): quem usou o quê, por qual token e por onde (app, REST, CLI ou MCP), incluindo toda leitura de conversa, toda negação e toda escrita.

Quando o token é recusado

Token ausente, malformado, inválido, expirado ou revogado responde 401 com WWW-Authenticate: Bearer realm="nexo", error="invalid_token":

{
  "type": "public_api.invalid_credential",
  "title": "InvalidCredentialError",
  "status": 401,
  "detail": "Token de acesso inválido, expirado ou revogado. Crie um novo token de acesso no Nexo.",
  "requestId": "019fcae7-…"
}

Muitas tentativas com token inválido do mesmo endereço (20 a cada 5 minutos) passam a receber 429 public_api.auth_failures_limited com Retry-After.

Boas práticas

Um token por uso (um para o Claude Code, outro para um script), cada um só com os escopos que precisa. Assim você revoga um sem derrubar os outros.
Guarde o token numa variável de ambiente ou num cofre de senhas; nunca no código nem num repositório.
Prefira a validade mais curta que der para o uso.

OAuth: o conector do Claude

O claude.ai e os apps do Claude não deixam configurar um cabeçalho com token, então o conector personalizado conecta por OAuth: o Claude abre a tela de consentimento no app do Nexo, você entra com a sua conta e autoriza. O acesso concedido age como você, com o seu papel, como um token pessoal, e você não precisa copiar token nenhum. O passo a passo está em Conectar ao Claude.