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/auth

A 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.

RotaAutenticação exigida
POST /auth/tokenPública - usuário/senha no corpo.
POST /auth/sessionCookie de sessão SSO (sem Bearer).
POST /auth/password-recoveryPública - sem token.
POST /auth/password-resetPública - o token do link de e-mail é a credencial.
GET /auth/meToken válido.
PUT /auth/meToken válido; recusa com 403 enquanto a senha for provisória.
PUT /auth/me/imagemToken válido.
POST /auth/change-passwordExige login de usuário (sessão); credenciais de integração recebem 403.
POST /auth/logoutToken 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âmetroTipoLocalObrigatórioDescrição
usernamestrformsimLogin ou e-mail cadastrado do usuário. Insensível a maiúsculas/minúsculas e a espaços nas pontas.
passwordstrformsimSenha do usuário. Comparada exatamente como enviada (diferencia maiúsculas e espaços).
rememberboolformnão"Manter conectado". Default false. Com true, o cookie de sessão SSO é persistente (até 7 dias); ignorado quando a senha é provisória.
grant_typestrformnãoPadrão OAuth2 (normalmente password).
scopestrformnãoIgnorado - 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=SENHA

Response 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 Unauthorized com message: "Credenciais inválidas" - login inexistente, conta inativa ou senha errada (indistinguíveis de propósito).
  • 401 Unauthorized com message: { "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çalho Retry-After indica 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 Forbidden com message: { "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; veja Retry-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).

CampoTipoObrigatórioDescrição
identificadorstrsimLogin ou e-mail (1 a 255 caracteres).
aplicacaostrnãoFront 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).

CampoTipoObrigatórioDescrição
tokenstrsimToken do link de redefinição (uso único, validade de 2h; até 512 caracteres).
nova_senhastrsimNova 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; veja Retry-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.

  1. POST /auth/token, POST /auth/session e GET /auth/me devolvem senha_provisoria: true - o front pode abrir a tela de troca obrigatória sem esperar o primeiro 403.
  2. O usuário chama POST /auth/change-password com a senha provisória em senha_atual e a nova senha. A marcação é zerada, as sessões anteriores são encerradas e a resposta traz um token novo, já com senha_provisoria: false.
  3. Alternativamente, concluir o fluxo público POST /auth/password-recovery → POST /auth/password-reset també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:

CampoTipoObrigatórioObservações
access_tokenstrsimJWT assinado. Enviar como Authorization: Bearer <token>.
token_typestrsimSempre "bearer".
expires_inintsimValidade do token em segundos.
rolestrsimPapel legado do usuário.
perfilstrsimPerfil de acesso do usuário.
scopesList[str]simEscopos embutidos no JWT.
senha_provisoriaboolsimtrue enquanto a senha em uso for provisória. Sempre false em POST /auth/change-password.

Schema do data de GET /auth/me

CampoTipoObservações
idintIdentificador do usuário.
nomestrNome do usuário.
emailstrE-mail do usuário.
loginstrLogin (usado no POST /auth/token).
usernamestrAlias de login - mesmo valor, campo aditivo para o front não decodificar o token.
substrAlias de login - mesmo valor do claim sub do JWT.
rolestrPapel legado. Não usar para autorização (ver nota abaixo).
perfilstrPerfil de acesso do usuário.
grupostr ou nullGrupo legado do usuário. null se o atributo faltar no usuário.
cargostrCargo do usuário.
setorstrSetor do usuário.
ativostrSituação da conta ("Ativo" ou "Desativado").
scopesList[str]Escopos efetivos do token.
expint ou nullExpiração do token, epoch em segundos (UTC). null quando não há expiração conhecida (não significa "expirado").
imagem_perfilstr ou nullFoto de perfil como data-URI base64 (jpeg/png/webp) ou null.
senha_provisoriabooltrue 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.

CampoTipoObservações
nomestrNome.
emailEmailStrE-mail. Não pode estar em uso por outra conta ativa (409).
senhastrNova senha em texto puro; passa pela política. Encerra as sessões.
telefonestrTelefone.
cpf, rg, orgao_emissor, pis, ctps, ctps_seriestrDocumentos do titular.
data_nascimentostrFormato YYYY-MM-DD.
cep, logradouro, numero, complemento, bairro, cidade, estadostrEndereço (estado = UF).

ChangePasswordRequest (corpo de POST /auth/change-password)

CampoTipoObrigatórioObservações
senha_atualstrsimSenha em uso (a provisória, no primeiro acesso). 1 a 128 caracteres.
nova_senhastrsimNova 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/session e POST /auth/change-password nã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": ... }, onde message é um texto ou, nos casos de senha provisória, um objeto { "codigo", "mensagem" }. A exceção são os 422 de 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 em 422 usa { "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/me com senha, POST /auth/password-reset ou a redefinição administrativa) invalida os JWTs e as sessões SSO emitidos antes da troca.
  • Desativar a conta de um usuário (ativo diferente de "Ativo") derruba, na requisição seguinte, as credenciais emitidas por ele.