Auth

Endpoints da WebApiAlcance para autenticação de usuários humanos. Cobrem a emissão de token JWT via usuário/senha (login) e a leitura dos dados do principal autenticado a partir do token. É por aqui que operadores da contabilidade obtêm o access_token que autoriza as demais chamadas da API.

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 demais rotas do domínio (GET /auth/me, PUT /auth/me/imagem, POST /auth/logout) também fogem da regra geral: não exigem escopo - basta um token válido (JWT humano ou API Key) para acessá-las, e elas sempre operam sobre os dados do próprio portador, nunca de 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

Request

Corpo em application/x-www-form-urlencoded (não JSON):

username=fvenas&password=SEGREDO

Response 200 OK

Este endpoint não usa o envelope { success, message, data }; devolve o payload OAuth2 diretamente:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "role": "admin",
  "perfil": "administrador",
  "scopes": ["*:*"]
}

O campo scopes reflete o perfil RBAC: ["*:*"] para administrador/diretoria (acesso global) ou a lista de escopos read/write do catálogo (exceto ações destrutivas) para funcionario. Credenciais inválidas retornam 401 Unauthorized (detail: "Credenciais inválidas"); o rate limit por IP excedido retorna 429 Too Many Requests (default 10 tentativas por 60s).

Escopo: público (não exige API Key)

GET /auth/me

Rota de identidade única do realm interno. Aceita tanto o JWT humano quanto uma API Key e devolve os campos públicos do principal 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:

{
  "success": true,
  "message": "Usuário autenticado recuperado com sucesso",
  "data": {
    "id": 7,
    "nome": "Felipe Venas",
    "email": "fvenas@alcancecontabilidade.com.br",
    "login": "fvenas",
    "username": "fvenas",
    "sub": "fvenas",
    "role": "admin",
    "perfil": "administrador",
    "grupo": "Administrador",
    "cargo": "TI",
    "setor": "Tecnologia",
    "ativo": "Ativo",
    "scopes": ["*:*"],
    "exp": 1751500000,
    "imagem_perfil": null
  }
}

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 autenticação foi feita por API Key (API Key não expira por sessão - null significa "sem expiração conhecida", não "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.

Escopo: nenhum - basta um token válido (JWT humano ou API Key) para acessar /auth/me.

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, independentemente de perfil.

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

{
  "success": true,
  "message": "Imagem de perfil atualizada com sucesso",
  "data": {
    "imagem_perfil": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Escopo: nenhum - exige apenas um token válido (JWT humano ou API Key), como o restante do domínio auth.

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

{
  "success": true,
  "message": "Logout efetuado com sucesso.",
  "data": {
    "revoked": true
  }
}

revoked indica se a revogação de sessão foi efetivada no servidor. Chamadas autenticadas por API Key retornam revoked: false - API Key não tem sessão a revogar; para desativá-la, use a gestão de chaves no Hub. 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.

Schemas

Schema da resposta de POST /auth/token

Este endpoint retorna um objeto OAuth2 (sem envelope):

Schema do data de GET /auth/me

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.

Notas

• POST /auth/token não segue o envelope { success, message, data } - devolve o payload OAuth2 (access_token, token_type, ...) diretamente. Já GET /auth/me, PUT /auth/me/imagem e POST /auth/logout usam o envelope padrão.
• O corpo do login é x-www-form-urlencoded (OAuth2), não JSON.
• As API Keys não são emitidas por /auth - este domínio trata exclusivamente do login humano por usuário/senha (e da leitura/edição da própria identidade).
• Desativar a conta de um usuário (ativo diferente de "Ativo") derruba, na requisição seguinte, tanto a sessão JWT viva quanto as API Keys emitidas por ele - a validação de token aplica a mesma checagem de conta ativa para os dois tipos de credencial.