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:
- Avise o TI em ti@alcancecontabilidade.com.br.
- Receba o novo token por canal seguro.
- Atualize o token em todos os clientes IA conectados.
- 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.