Auth
Endpoints da WebApiAlcance para autenticação de usuários. Cobrem a emissão de token JWT via usuário/senha (login), a retomada de sessão por cookie (SSO), a leitura e edição dos dados do principal autenticado, a troca e a recuperação de senha e o logout. É por aqui que operadores da contabilidade obtêm o access_token que autoriza as demais chamadas da API.
Para o panorama completo de autenticação (JWT de login vs. API Key e escopos), veja Autenticação.
Base path
/api/v1/authA URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/auth.
Escopos necessários
Este domínio é especial e não segue o padrão de escopos das demais rotas: as rotas de /auth ficam fora da derivação automática de escopo e fora do bloqueio por senha provisória. Nenhuma rota de /auth exige escopo.
| Rota | Autenticação exigida |
|---|---|
POST /auth/token | Pública - usuário/senha no corpo. |
POST /auth/session | Cookie de sessão SSO (sem Bearer). |
POST /auth/password-recovery | Pública - sem token. |
POST /auth/password-reset | Pública - o token do link de e-mail é a credencial. |
GET /auth/me | Token válido. |
PUT /auth/me | Token válido; recusa com 403 enquanto a senha for provisória. |
PUT /auth/me/imagem | Token válido. |
POST /auth/change-password | Exige login de usuário (sessão); credenciais de integração recebem 403. |
POST /auth/logout | Token válido. |
Token é público
POST /auth/token é o ponto de entrada público da API - login por usuário/senha que emite o JWT. Não exige escopo nem token prévio: é justamente o endpoint que gera o token.
As rotas autenticadas do domínio sempre operam sobre os dados do próprio portador - nenhuma delas recebe id de usuário, então não existe como apontá-las para terceiros.
Endpoints
POST /auth/token
Autentica o usuário por usuário e senha e gera um token de acesso JWT. É o ponto de entrada público da API - não exige token nem escopo prévio. O corpo é enviado como application/x-www-form-urlencoded (padrão OAuth2 OAuth2PasswordRequestForm), não como JSON.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
username | str | form | sim | Login ou e-mail cadastrado do usuário. Insensível a maiúsculas/minúsculas e a espaços nas pontas. |
password | str | form | sim | Senha do usuário. Comparada exatamente como enviada (diferencia maiúsculas e espaços). |
remember | bool | form | não | "Manter conectado". Default false. Com true, o cookie de sessão SSO é persistente (até 7 dias); ignorado quando a senha é provisória. |
grant_type | str | form | não | Padrão OAuth2 (normalmente password). |
scope | str | form | não | Ignorado - os escopos são derivados do perfil de acesso do usuário. |
Login por login ou e-mail
O campo username aceita tanto o login quanto o e-mail cadastrado do usuário. Credenciais que não possam ser resolvidas a uma única conta ativa retornam 401 - contas desativadas nunca autenticam.
Request
Corpo em application/x-www-form-urlencoded (não JSON):
username=usuario.exemplo&password=SENHAResponse 200 OK
Este endpoint não usa o envelope { status, message, data }; devolve o payload OAuth2 diretamente:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 28800,
"role": "<role>",
"perfil": "<perfil>",
"scopes": ["customers:read"],
"senha_provisoria": false
}O campo scopes traz a lista de escopos autorizados do usuário. expires_in é a validade do token em segundos (configurável no servidor). senha_provisoria é true quando a senha usada foi gerada pelo servidor e ainda não foi trocada - o front deve abrir a troca obrigatória (ver Senha provisória).
Além do corpo, a resposta define o cookie de sessão (SSO), usado por POST /auth/session.
Erros (corpo { "message": ... }):
401 Unauthorizedcommessage: "Credenciais inválidas"- login inexistente, conta inativa ou senha errada (indistinguíveis de propósito).401 Unauthorizedcommessage: { "codigo": "SENHA_PROVISORIA_EXPIRADA", "mensagem": "..." }- senha correta, mas é uma senha provisória não trocada em 7 dias.429 Too Many Requests- limite de tentativas excedido; o cabeçalhoRetry-Afterindica quando tentar de novo.
Escopo: público (não exige token)
POST /auth/session
Troca o cookie de sessão (SSO) por um access token novo. É ao mesmo tempo o mecanismo de renovação (fim da validade do token) e o de SSO: qualquer app do domínio recupera a sessão sem tela de login. A cada chamada o cookie é rotacionado e o perfil/scopes são re-resolvidos a cada renovação.
Parâmetros
Este endpoint não recebe parâmetros de rota, query nem corpo - a credencial é o cookie de sessão (SSO) emitido por POST /auth/token (ou POST /auth/change-password).
Request
Sem corpo de requisição. Sem header Authorization.
Response 200 OK
Mesmo formato do POST /auth/token (sem envelope), com o cookie rotacionado em Set-Cookie:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 28800,
"role": "<role>",
"perfil": "<perfil>",
"scopes": ["customers:read", "customers:write"],
"senha_provisoria": false
}Qualquer recusa retorna 401 Unauthorized com message: "session_expired": cookie ausente, sessão inválida/revogada, conta inexistente ou inativa, senha provisória vencida, ou sessão criada antes da última troca de senha. Sujeita a limite de tentativas; ao exceder, 429 com Retry-After.
Escopo: nenhum - autenticado pelo cookie de sessão.
GET /auth/me
Rota de identidade única. Disponível a qualquer credencial autenticada; devolve os campos públicos do usuário autenticado com os escopos efetivos resolvidos para o token, sempre refletindo o estado atual da conta - tokens de sessões encerradas ou de contas desativadas recebem 401.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - o principal é resolvido a partir do token enviado no header Authorization.
Request
Sem corpo de requisição.
Response 200 OK
Envelope padrão success_response:
{
"status": "success",
"message": "Usuário autenticado recuperado com sucesso",
"data": {
"id": 7,
"nome": "Usuário Exemplo",
"email": "usuario.exemplo@exemplo.com.br",
"login": "usuario.exemplo",
"username": "usuario.exemplo",
"sub": "usuario.exemplo",
"role": "<role>",
"perfil": "<perfil>",
"grupo": "<grupo>",
"cargo": "Analista",
"setor": "Exemplo",
"ativo": "Ativo",
"scopes": ["customers:read"],
"exp": 1751500000,
"imagem_perfil": null,
"senha_provisoria": false
}
}username e sub são aliases de login (mesmo valor do claim sub do JWT) - existem para o front ler a identidade direto da resposta, sem decodificar o token no cliente. exp é a expiração do token em epoch/segundos (UTC) e vem null quando a credencial não tem expiração conhecida (null não significa "expirado"). imagem_perfil é a foto de perfil como data-URI base64 (data:image/(jpeg|png|webp);base64,...) ou null se o usuário não tiver foto cadastrada. senha_provisoria é true enquanto a senha em uso for a provisória gerada pelo servidor; é false quando não se aplica.
GET /auth/me continua respondendo mesmo com a senha provisória - é uma das rotas que o gate deixa abertas para o usuário conseguir sair do estado.
Escopo: nenhum - basta um token válido para acessar /auth/me.
PUT /auth/me
Atualiza os próprios dados cadastrais do usuário autenticado. Rota self-service: disponível a qualquer usuário autenticado, sem passar pela gestão de usuários do Hub. O alvo é sempre o próprio usuário - não há parâmetro de id.
O corpo é uma allowlist estreita (PerfilSelfUpdate): perfil, role, ativo, grupo, setor, cargo, login e imagem_perfil não fazem parte dela e são ignorados se enviados. Atualização parcial: só os campos presentes no corpo são alterados.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
{
"nome": "Maria Souza",
"email": "maria.souza@exemplo.com.br",
"telefone": "71999998888"
}senha (opcional) vai em texto puro e passa pela política de senha do servidor (mínimo de 12 caracteres, entre outras regras). Trocar a senha por aqui encerra as sessões anteriores.
Response 200 OK
{
"status": "success",
"message": "Perfil atualizado com sucesso",
"data": {
"id": 7,
"nome": "Maria Souza",
"email": "maria.souza@exemplo.com.br",
"login": "maria.souza",
"telefone": "71999998888",
"sessao_encerrada": false
}
}Quando a senha foi trocada, sessao_encerrada vem true e a mensagem orienta a entrar novamente - o front deve mandar o usuário ao login.
Erros (corpo { "message": ... }):
403 Forbiddencommessage: { "codigo": "SENHA_PROVISORIA", "mensagem": "..." }- a rota é recusada inteira enquanto a senha for provisória (a saída éPOST /auth/change-password).409 Conflict- o e-mail informado já está em uso por outra conta ativa.422 Unprocessable Entity- nova senha reprovada pela política (ou e-mail com formato inválido).404 Not Found- usuário removido entre a autenticação e a escrita.
Escopo: nenhum - exige apenas um token válido.
PUT /auth/me/imagem
Define ou remove a própria foto de perfil do usuário autenticado - contraparte de escrita do campo imagem_perfil que GET /auth/me devolve. Rota self-service: disponível a qualquer usuário autenticado, para qualquer usuário.
O alvo é sempre o próprio usuário autenticado: não há parâmetro de id na rota, então não existe como apontar a escrita para outro usuário.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Corpo JSON com um único campo:
{
"imagem_perfil": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}Enviar {"imagem_perfil": null} (ou omitir o campo com corpo {}) remove a foto atual. Data-URI fora do padrão (jpeg/png/webp), base64 inválido, imagem acima de 500KB decodificados ou magic bytes incoerentes com o MIME declarado retornam 422 Unprocessable Entity.
Response 200 OK
{
"status": "success",
"message": "Imagem de perfil atualizada com sucesso",
"data": {
"imagem_perfil": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
}Escopo: nenhum - exige apenas um token válido, como o restante do domínio auth.
POST /auth/change-password
Troca a senha do próprio titular, encerra todas as sessões anteriores (em todos os dispositivos) e devolve um token novo. É a saída do estado de senha provisória: fica aberta mesmo com a senha provisória, e zera a marcação ao concluir. Funciona também para quem já tem senha definitiva.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (ChangePasswordRequest).
Request
{
"senha_atual": "SenhaProvisoriaRecebida",
"nova_senha": "uma frase longa que eu lembro"
}senha_atual é exigida sempre, inclusive no primeiro acesso com a provisória. A nova_senha passa pela política do servidor (mínimo de 12 caracteres, máximo de 128, e não pode ser igual à atual, entre outras regras). Campos extras no corpo são rejeitados (422).
Response 200 OK
Mesmo formato do POST /auth/token (sem envelope), com senha_provisoria: false e um cookie de sessão (SSO) novo (cookie de sessão, sem "manter conectado"):
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 28800,
"role": "<role>",
"perfil": "<perfil>",
"scopes": ["customers:read", "customers:write"],
"senha_provisoria": false
}O token emitido aqui é o único que sobrevive: o Bearer usado na chamada é revogado, e JWTs e sessões SSO anteriores à troca passam a ser recusados.
Erros (corpo { "message": ... }):
400 Bad Request- senha atual incorreta ou nova senha reprovada pela política (400, e não 401, para o front não confundir com sessão expirada).403 Forbidden- chamada sem login de usuário (credenciais de integração).429 Too Many Requests- limite de tentativas excedido; vejaRetry-After.
Escopo: nenhum - exige login de usuário (sessão); credenciais de integração recebem 403.
POST /auth/password-recovery
Etapa 1 de 2 da recuperação de senha ("esqueci minha senha"). Rota pública: se existir uma conta ativa com o identificador informado, envia um e-mail com o link de redefinição (válido por 2 horas). Responde sempre 202, com o mesmo corpo, exista ou não a conta - a rota não revela quem tem cadastro.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (PasswordRecoveryRequest).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
identificador | str | sim | Login ou e-mail (1 a 255 caracteres). |
aplicacao | str | não | Front interno de onde o pedido saiu, que decide para onde o link aponta: hub, certidao, contabil, nfse, analytics ou bobtax. Ausente = hub. Outro valor é 422. A URL vem sempre da configuração da API, nunca do request. |
Request
{
"identificador": "maria.souza",
"aplicacao": "hub"
}Response 202 Accepted
{
"status": "success",
"message": "Se existir uma conta com esse login ou e-mail, enviamos um link para redefinir a senha. O link vale por 2 horas.",
"data": {
"enviado": true
}
}enviado: true é constante e não confirma que um e-mail saiu. Campos extras ou aplicacao fora da lista retornam 422. A rota é sujeita a limite de tentativas; ao exceder, 429 com Retry-After.
Escopo: público (não exige token)
POST /auth/password-reset
Etapa 2 de 2 da recuperação de senha. Rota pública - o token recebido no link do e-mail é a credencial. Define a nova senha e encerra as sessões anteriores, mas não devolve sessão nem token: depois de redefinir, o usuário entra pelo POST /auth/token com a senha nova.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (PasswordResetRequest).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
token | str | sim | Token do link de redefinição (uso único, validade de 2h; até 512 caracteres). |
nova_senha | str | sim | Nova senha (até 200 caracteres no schema). O mínimo de 12 caracteres e as demais recusas vêm da política do servidor. |
Request
{
"token": "f3Kx9...token-do-link...",
"nova_senha": "uma frase longa que eu lembro"
}Response 200 OK
{
"status": "success",
"message": "Senha redefinida. As sessões anteriores foram encerradas — entre com a senha nova.",
"data": {
"redefinida": true
}
}Erros (corpo { "message": ... }), com tratamento diferente no front:
400 Bad Request- token inválido, expirado ou já usado. Terminal: o usuário deve pedir um link novo.422 Unprocessable Entity- nova senha reprovada pela política (ou corpo inválido). O formulário continua aberto para correção, e o token segue válido.429 Too Many Requests- limite de tentativas excedido; vejaRetry-After.
Escopo: público (não exige token)
POST /auth/logout
Encerra a sessão do usuário autenticado, revogando o JWT atual no servidor - depois do logout, o mesmo token deixa de ser aceito pelas rotas da API. Se a requisição trouxer o cookie de sessão SSO, a sessão inteira é revogada (com os tokens que outros apps do domínio obtiveram por ela) e o cookie é limpo. Requer autenticação (o próprio token a revogar, no header Authorization).
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Logout efetuado com sucesso.",
"data": {
"revoked": true
}
}revoked indica se a revogação do token apresentado foi efetivada no servidor. Quando não há sessão a revogar, revoked vem false. Em qualquer caso, o cliente deve descartar o token localmente após o logout.
Escopo: nenhum - exige apenas um token válido, como o restante do domínio auth.
Redefinição administrativa de senha
A redefinição da senha de outro usuário (feita pelo Hub) não fica em /auth: é a rota POST /users/{user_id}/redefinir-senha, documentada em Users. Ela cria o estado de senha provisória descrito abaixo.
Senha provisória
Uma senha é provisória quando foi definida pelo servidor e outra pessoa a conheceu: na criação de usuário sem senha ou na redefinição pela gestão de usuários (ver Users). Enquanto o titular não a troca, a API bloqueia as rotas de dados para ele.
Onde é aplicado. O bloqueio vale para todas as rotas de dados. As rotas de /auth ficam fora dele, e há uma lista explícita (GET /auth/me, POST /auth/logout, POST /auth/change-password) para o usuário nunca ficar preso sem conseguir sair do estado.
O que bloqueia. Qualquer requisição autenticada de um usuário com senha provisória, em qualquer rota de dados, recebe:
{
"message": {
"codigo": "SENHA_PROVISORIA",
"mensagem": "Sua senha é provisória. Faça o primeiro acesso pelo Hub para definir uma senha sua — enquanto isso, o acesso aos dados fica bloqueado."
}
}com status 403 Forbidden. O front deve tratar pelo codigo, não pelo texto. PUT /auth/me também é recusada com o mesmo codigo (por guarda própria da rota).
Como sinalizar e sair.
POST /auth/token,POST /auth/sessioneGET /auth/medevolvemsenha_provisoria: true- o front pode abrir a tela de troca obrigatória sem esperar o primeiro403.- O usuário chama
POST /auth/change-passwordcom a senha provisória emsenha_atuale a nova senha. A marcação é zerada, as sessões anteriores são encerradas e a resposta traz um token novo, já comsenha_provisoria: false. - Alternativamente, concluir o fluxo público
POST /auth/password-recovery→POST /auth/password-resettambém zera a marcação (quem definiu a senha passa a ser o titular).
Prazo. A senha provisória vale 7 dias. Depois disso o login (POST /auth/token) recusa com 401 e codigo: "SENHA_PROVISORIA_EXPIRADA", e POST /auth/session deixa de renovar (session_expired). A saída passa a ser pedir uma nova senha ao TI Alcance, ou usar o fluxo público POST /auth/password-recovery → POST /auth/password-reset.
Schemas
Schema da resposta de POST /auth/token
Este endpoint retorna um objeto OAuth2 (sem envelope). POST /auth/session e POST /auth/change-password devolvem o mesmo formato:
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
access_token | str | sim | JWT assinado. Enviar como Authorization: Bearer <token>. |
token_type | str | sim | Sempre "bearer". |
expires_in | int | sim | Validade do token em segundos. |
role | str | sim | Papel legado do usuário. |
perfil | str | sim | Perfil de acesso do usuário. |
scopes | List[str] | sim | Escopos embutidos no JWT. |
senha_provisoria | bool | sim | true enquanto a senha em uso for provisória. Sempre false em POST /auth/change-password. |
Schema do data de GET /auth/me
| Campo | Tipo | Observações |
|---|---|---|
id | int | Identificador do usuário. |
nome | str | Nome do usuário. |
email | str | E-mail do usuário. |
login | str | Login (usado no POST /auth/token). |
username | str | Alias de login - mesmo valor, campo aditivo para o front não decodificar o token. |
sub | str | Alias de login - mesmo valor do claim sub do JWT. |
role | str | Papel legado. Não usar para autorização (ver nota abaixo). |
perfil | str | Perfil de acesso do usuário. |
grupo | str ou null | Grupo legado do usuário. null se o atributo faltar no usuário. |
cargo | str | Cargo do usuário. |
setor | str | Setor do usuário. |
ativo | str | Situação da conta ("Ativo" ou "Desativado"). |
scopes | List[str] | Escopos efetivos do token. |
exp | int ou null | Expiração do token, epoch em segundos (UTC). null quando não há expiração conhecida (não significa "expirado"). |
imagem_perfil | str ou null | Foto de perfil como data-URI base64 (jpeg/png/webp) ou null. |
senha_provisoria | bool | true enquanto a senha em uso for a provisória gerada pelo servidor. false quando não se aplica. |
Este endpoint é aditivo por contrato: novos campos podem ser acrescentados em versões futuras, mas nenhum campo existente é removido ou renomeado sem quebra de versão. Os dados pessoais do titular (CPF, RG, PIS, CTPS, data de nascimento, telefone e endereço) não são expostos aqui de propósito.
PerfilSelfUpdate (corpo de PUT /auth/me)
Todos os campos são opcionais; apenas os enviados são atualizados. Campos fora da lista são ignorados.
| Campo | Tipo | Observações |
|---|---|---|
nome | str | Nome. |
email | EmailStr | E-mail. Não pode estar em uso por outra conta ativa (409). |
senha | str | Nova senha em texto puro; passa pela política. Encerra as sessões. |
telefone | str | Telefone. |
cpf, rg, orgao_emissor, pis, ctps, ctps_serie | str | Documentos do titular. |
data_nascimento | str | Formato YYYY-MM-DD. |
cep, logradouro, numero, complemento, bairro, cidade, estado | str | Endereço (estado = UF). |
ChangePasswordRequest (corpo de POST /auth/change-password)
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
senha_atual | str | sim | Senha em uso (a provisória, no primeiro acesso). 1 a 128 caracteres. |
nova_senha | str | sim | Nova senha. 1 a 200 caracteres no schema; a política exige de 12 a 128. |
Campos extras são rejeitados (422). PasswordRecoveryRequest e PasswordResetRequest estão descritos nas respectivas rotas, e também rejeitam campos extras.
Notas
Rate limit nas rotas de credencial
As rotas de credencial estão sujeitas a limite de tentativas. Ao exceder, a API retorna 429 Too Many Requests com Retry-After - aguarde e tente novamente.
Senha provisória fecha as rotas de dados
Com a senha provisória, o usuário recebe 403 com codigo: "SENHA_PROVISORIA" em qualquer rota de dados. Só GET /auth/me, POST /auth/logout e POST /auth/change-password seguem utilizáveis (além das rotas públicas). Veja Senha provisória.
role não autoriza nada
role é um campo legado, mantido apenas por compatibilidade de contrato - ele não determina permissões. A autorização do usuário é governada pelo perfil de acesso.
POST /auth/token,POST /auth/sessionePOST /auth/change-passwordnão seguem o envelope{ status, message, data }- devolvem o payload OAuth2 (access_token,token_type, ...) diretamente. As demais rotas usam o envelope padrão{ "status": "success", "message": ..., "data": ... }.- Respostas de erro (
HTTPException) saem como{ "message": ... }, ondemessageé um texto ou, nos casos de senha provisória, um objeto{ "codigo", "mensagem" }. A exceção são os422de validação de schema (campo faltando, campo extra, tipo errado), que mantêm o formato do FastAPI{ "detail": [...] }; já a recusa da política de senha em422usa{ "message": ... }. - O corpo do login é
x-www-form-urlencoded(OAuth2), não JSON. As demais rotas com corpo recebem JSON. - Este domínio trata do login por usuário/senha, da sessão e da própria identidade.
- Trocar a senha (
POST /auth/change-password,PUT /auth/mecomsenha,POST /auth/password-resetou a redefinição administrativa) invalida os JWTs e as sessões SSO emitidos antes da troca. - Desativar a conta de um usuário (
ativodiferente de"Ativo") derruba, na requisição seguinte, as credenciais emitidas por ele.