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. O mesmo header aceita JWT ou 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) 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 de acesso do usuário e a lista de scopes autorizada. O campo role também é devolvido por compatibilidade, mas é um campo legado que não determina permissões.

O cliente envia esse JWT em todas as chamadas subsequentes:

Authorization: Bearer <jwt>

O token vale 480 minutos contados do login (expires_in, em segundos, na resposta) e não é renovado pela atividade. Após expirar, retorna 401.

Para renovar sem pedir a senha de novo, use POST /auth/session: o login também emite um cookie de sessão (SSO) que o endpoint troca por um JWT novo. Não há /auth/refresh. O fim da sessão é feito por POST /auth/logout, que revoga o token e a sessão SSO.

Os endpoints de login, sessão e recuperação de senha limitam as tentativas - exceder retorna 429 Too Many Requests com o header Retry-After (segundos).

Senha provisória

Usuários criados sem senha, ou com a senha redefinida por um responsável, recebem uma senha provisória:

  • POST /auth/token, POST /auth/session e GET /auth/me informam senha_provisoria: true.
  • Enquanto for provisória, as rotas de dados respondem 403 com { "message": { "codigo": "SENHA_PROVISORIA", "mensagem": "..." } }. Seguem liberadas GET /auth/me, POST /auth/logout e POST /auth/change-password.
  • A provisória vale por 7 dias; depois disso o login retorna 401 com { "message": { "codigo": "SENHA_PROVISORIA_EXPIRADA", "mensagem": "..." } } e é preciso solicitar a redefinição.
  • POST /auth/change-password troca a senha, encerra os tokens e sessões anteriores (de todos os dispositivos) e devolve um token novo. A troca de senha por qualquer outro caminho (PUT /auth/me, recuperação por e-mail) também encerra as sessões anteriores.

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 mesmo header aceita tanto um JWT quanto uma API Key.

Diferenças práticas

CaracterísticaJWTAPI Key
AudiênciaOperadores humanos via UIAutomações / integrações
OrigemLogin com usuário + senhaEmissão pelo Hub
Validade480 minutos a partir do loginPersonalizada através do Hub
EscoposDerivados do perfil de acesso do usuárioPersonalizado através do Hub
RevogaçãoPOST /auth/logout, troca de senha ou expiraçãoPersonalizado através do Hub
RenovaçãoPOST /auth/session ou novo login em /auth/tokenRotação manual ou reativação no Hub

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@exemplo.com.br&password=SENHA"
 
# Resposta:
# {
#   "access_token": "eyJhbGciOi...",
#   "token_type": "bearer",
#   "expires_in": 28800,
#   "role": "<role>",
#   "perfil": "<perfil>",
#   "scopes": ["customers:read"],
#   "senha_provisoria": false
# }

role é um campo legado, mantido apenas por compatibilidade - não determina permissões. A autorização do usuário é governada pelo perfil de acesso.

Erros comuns

  • 401 Unauthorized - token ausente, malformado ou expirado. Mensagem "Nao foi possivel validar as credenciais"; a resposta traz WWW-Authenticate: Bearer. Para JWT, renove em /auth/session ou reautentique; para API Key, verifique se a chave foi desativada. Tokens emitidos antes de uma troca de senha também retornam 401.
  • 403 Forbidden - credencial válida, mas escopo insuficiente para o recurso. Mensagem "Escopo necessario: <recurso>:<acao>". Solicite ampliação de escopo ao TI Alcance. Além do escopo, algumas rotas exigem permissão adicional do usuário ou login de usuário; nesses casos a resposta sem permissão é 403.
  • 403 Forbidden com codigo: "SENHA_PROVISORIA" - a senha em uso é provisória. Troque-a em POST /auth/change-password.
  • 429 Too Many Requests - limite de tentativas nos endpoints de autenticação. Aguarde os segundos indicados no header Retry-After.

API Keys equivalem a senha

Uma API Key concede acesso direto à WebApi sob a identidade do usuário emissor. Trate-a como credencial sensível:

  • Nunca commite em repositório, mesmo privado.
  • Nunca logue em STDOUT, arquivos de log ou ferramentas de observabilidade.
  • Rotacione a cada 90 dias - gere nova chave, atualize o consumidor, então desative a antiga.
  • Use HTTPS sempre. Bearer trafega em texto puro dentro do header.
  • Em caso de suspeita de vazamento, solicite imediatamente a desativação da chave no Hub.