Autenticação

A WebApiAlcance suporta dois mecanismos de autenticação distintos, escolhidos conforme o tipo de consumidor - uma pessoa logando via UI ou um sistema automatizado consumindo a API. Os dois esquemas convivem no mesmo middleware: a API tenta primeiro decodificar como JWT; se falhar, faz fallback para API Key.

Ambos os mecanismos usam o esquema Bearer no header Authorization - a distinção é feita pelo formato do conteúdo do token, não pelo nome do header.

Caminho A - JWT (operadores humanos)

Operadores humanos (contadores, analistas, administradores) autenticam por login (ou e-mail) e senha no endpoint:

POST /api/v1/auth/token

A requisição segue o padrão OAuth2 Password Flow - formato application/x-www-form-urlencoded, campos username e password. O campo username aceita o login ou o e-mail cadastrado, de forma insensível a maiúsculas/minúsculas e a espaços nas pontas. A senha é comparada exatamente como enviada (diferencia maiúsculas e espaços). Credenciais que não possam ser resolvidas a uma única conta ativa retornam 401.

A resposta devolve um JWT assinado com a chave secreta do servidor, contendo o sub (login), o perfil RBAC do usuário (administrador, diretoria ou funcionario, base da autorização) e a lista de scopes autorizada. O campo role também é devolvido por compatibilidade, mas é uma coluna legada que não determina permissões.

O cliente envia esse JWT em todas as chamadas subsequentes:

Authorization: Bearer <jwt>

O token tem validade limitada (configurada via ACCESS_TOKEN_EXPIRE_MINUTES no servidor) - após expirar, retorna 401 e o operador precisa reautenticar.

O endpoint /auth/token é protegido por rate limit (padrão 10 tentativas / 60 segundos por IP) - exceder retorna 429 Too Many Requests.

Caminho B - API Key (automações)

Sistemas automatizados (gateway MCP, integrações parceiras, scripts internos) autenticam com uma API Key de longa duração, emitida e administrada pelo Hub - o painel interno da Alcance.

A API Key é vinculada a um usuário emissor, recebe um conjunto explícito de escopos (recurso:acao) e pode ter data de expiração opcional. Após criada, a chave em texto plano é exibida apenas uma vez - guarde-a em cofre seguro.

O cliente envia a API Key no mesmo header que o JWT:

Authorization: Bearer <api_key>

O middleware tenta decodificar como JWT primeiro; ao falhar, valida como API Key consultando o banco. Os escopos são cacheados por 30 segundos por API Key para reduzir latência.

Diferenças práticas

Exemplo curl

# Caminho A - JWT (login humano, aceita login ou e-mail em "username")
curl -X POST https://api.contabilidadealcance.com.br/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=operador@alcance.com.br&password=SENHA"
 
# Resposta:
# {
#   "access_token": "eyJhbGciOi...",
#   "token_type": "bearer",
#   "role": "admin",
#   "perfil": "administrador",
#   "scopes": ["*:*"]
# }

role é um campo legado, mantido apenas por compatibilidade - não determina permissões. Quem governa a autorização é o perfil, como no exemplo acima.

Erros comuns

• 401 Unauthorized - token ausente, malformado ou expirado. Detalhe "Nao foi possivel validar as credenciais". Para JWT, reautentique; para API Key, verifique se a chave foi desativada.
• 403 Forbidden - credencial válida, mas escopo insuficiente para o recurso. Detalhe "Escopo necessario: <recurso>:<acao>". Solicite ampliação de escopo ao admin Alcance.
• 429 Too Many Requests - rate limit em /auth/token. Aguarde a janela (60s por padrão) antes de tentar novamente.