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/tokenA 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/sessioneGET /auth/meinformamsenha_provisoria: true.- Enquanto for provisória, as rotas de dados respondem 403 com
{ "message": { "codigo": "SENHA_PROVISORIA", "mensagem": "..." } }. Seguem liberadasGET /auth/me,POST /auth/logoutePOST /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-passwordtroca 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ística | JWT | API Key |
|---|---|---|
| Audiência | Operadores humanos via UI | Automações / integrações |
| Origem | Login com usuário + senha | Emissão pelo Hub |
| Validade | 480 minutos a partir do login | Personalizada através do Hub |
| Escopos | Derivados do perfil de acesso do usuário | Personalizado através do Hub |
| Revogação | POST /auth/logout, troca de senha ou expiração | Personalizado através do Hub |
| Renovação | POST /auth/session ou novo login em /auth/token | Rotaçã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 trazWWW-Authenticate: Bearer. Para JWT, renove em/auth/sessionou 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 emPOST /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.