Autenticação Bearer

Bearer Token é um esquema de autenticação HTTP padronizado pela RFC 6750. O cliente envia, em cada requisição, o header:

Authorization: Bearer <token>

A semântica é literal - "quem porta o token é tratado como autenticado". Isso significa que o token, sozinho, é a credencial: não há challenge, não há nonce, não há rotação automática. Toda a segurança vem da confidencialidade do token (HTTPS obrigatório).

Como funciona na plataforma Alcance

A Alcance usa Bearer em duas camadas distintas - entender a diferença evita confusão na hora de configurar integrações.

1. Cliente IA → MCP gateway

O cliente IA (Claude Desktop, Cursor, Lovable) é configurado com o token do MCP, emitido pela Alcance para cada integração. Em toda chamada (tools/list, tools/call, resources/read), ele envia o header Authorization: Bearer <token>.

O gateway responde 401 Unauthorized quando o token está ausente, malformado ou inválido.

2. MCP gateway → WebApiAlcance

Validado o cliente IA, o gateway encaminha a chamada para a WebApiAlcance usando outra credencial - uma API Key dedicada ao MCP, também enviada no padrão Bearer. Essa API Key é restrita por escopos (recurso:acao), nunca global, e é validada pelo FastAPI da WebApi.

São, portanto, dois Bearer tokens distintos no mesmo fluxo, com responsabilidades separadas: o token do MCP autentica o cliente IA perante o gateway; a API Key autentica o gateway perante a API de negócio.

Exemplo de chamada

curl -X POST https://mcp.contabilidadealcance.com.br/api/mcp \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Resposta esperada com token válido: JSON com a lista de tools registradas. Com token inválido: HTTP 401 + corpo JSON {"error":"unauthorized"}.

Boas práticas

  • Rotacionar a cada 90 dias, com lembrete no calendário.
  • Nunca commitar o token em repositório, mesmo privado. Use um cofre de segredos ou arquivo de ambiente local fora do versionamento.
  • Nunca logar o token em STDOUT, arquivos de log, ferramentas de observabilidade ou mensagens de erro.
  • HTTPS sempre. O Bearer é trafegado em texto puro dentro do header - sem TLS, qualquer proxy intermediário lê o token.
  • Tokens longos. O token deve ter no mínimo 32 bytes de entropia (use openssl rand -base64 32).

Vazamento de token

Se houver suspeita de vazamento do token - push acidental em repositório, screenshot publicado, dispositivo comprometido - solicite a rotação imediata ao TI Alcance:

  1. Avise o TI em ti@alcancecontabilidade.com.br.
  2. Receba o novo token por canal seguro.
  3. Atualize o token em todos os clientes IA conectados.
  4. Desative o token antigo após a confirmação.

Migração para OAuth 2.1

O Bearer é o mecanismo de autenticação atual do gateway.

A Alcance planeja migrar para OAuth 2.1 com Dynamic Client Registration (DCR), ganhando: revogação granular por cliente e - fundamental - suporte ao ChatGPT, que exige OAuth 2.1. O modo Bearer será mantido como fallback durante a transição.