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 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. A resposta devolve um JWT assinado com a chave secreta do servidor, contendo o sub (login), o role do usuário (admin ou user) e a lista de scopes autorizada.

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 pela própria WebApi e administrada via endpoint:

POST /api/v1/api-keys/

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)
curl -X POST https://api.contabilidadealcance.com.br/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=operador@alcance&password=SENHA"
 
# Resposta:
# {
#   "access_token": "eyJhbGciOi...",
#   "token_type": "bearer",
#   "role": "user",
#   "scopes": ["customers:read", "lembretes:read"]
# }
 
# Caminho B — API Key (automação)
curl -H "Authorization: Bearer SEU_API_KEY" \
  https://api.contabilidadealcance.com.br/api/v1/customers/

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.