Jornada Alteração/Recuperação de Senha

Diagrama do Fluxo

Representação documental dos dois fluxos descritos nesta jornada: alteração (usuário logado) e recuperação (usuário deslogado), ambos com validação OTP.

Esta API fornece os endpoints para que usuários autenticados possam alterar sua senha de acesso e para que usuários não autenticados possam recuperar uma senha esquecida.

Visão Geral

A jornada de alteração e recuperação de senha é dividida em dois fluxos principais:

Fluxo de Alteração de Senha (Usuário Logado):

1. O cliente chama /security/me/password/mail/otp/challenge para receber um código via e-mail
2. O cliente chama /security/me/password/mail/otp/validate para validar o código recebido
3. (Opcional, se mais fatores forem necessários) O cliente chama os endpoints de SMS (/sms/otp/...)
4. Após a validação dos desafios, o cliente chama /v2/security/me/password/change com a nova senha

Fluxo de Recuperação de Senha (Usuário Deslogado):

1. O cliente chama /security/password/recover/challenge (ou /mail/challenge) informando o documento do usuário para receber um código de recuperação
2. O cliente chama /security/password/recovery/validate (ou /mail/validate) para validar o código
3. Após a validação, o cliente chama /security/password/recovery para definir a nova senha

---

1. Gerar Desafio OTP por Email (Alteração)

Gera um desafio OTP por e-mail para alterar a senha

Inicia o fluxo de alteração de senha para um usuário autenticado, enviando um código de uso único (OTP) para o e-mail cadastrado.

Endpoint: POST /security/me/password/mail/otp/challenge

Headers:

X-BuildersBank-Authorization: {token_de_sessao}
Content-Type: application/json

Resposta de Sucesso (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 3
}

Possíveis Erros:

• 401 - Não autorizado (token ausente ou inválido)
• 403 - Proibido (token válido, mas não possui o escopo 'accounts-consumer')

2. Validar Desafio OTP de Email (Alteração)

Valida o desafio OTP de e-mail

Valida o código OTP que o usuário recebeu por e-mail.

Endpoint: POST /security/me/password/mail/otp/validate

Headers:

X-BuildersBank-Authorization: {token_de_sessao}
Content-Type: application/json

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456"
}

Resposta de Sucesso (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 2
}

Possíveis Erros:

• 400 - Requisição inválida ou OTP incorreto
• 401 - Não autorizado
• 403 - Proibido

3. Efetuar Alteração da Senha

Efetiva a alteração da senha

Após a validação bem-sucedida dos desafios (OTP), este endpoint define a nova senha para o usuário.

Endpoint: POST /v2/security/me/password/change

Headers:

X-BuildersBank-Authorization: {token_de_sessao}
Content-Type: application/json

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "credential": "NewStrongP@ssw0rd!",
  "oldCredential": "OldP@ssw0rd123"
}

Resposta de Sucesso (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...",
  "refreshToken": "def502006a2c63c033a8a7a3f4c4a24a...",
  "expiresIn": 86400
}

Possíveis Erros:

• 400 - Requisição inválida (ex: senha não atende aos critérios de segurança)
• 401 - Não autorizado
• 403 - Proibido

4. Gerar Desafio OTP para Recuperação

Gera um desafio OTP por SMS para recuperar a senha

Inicia o fluxo de recuperação de senha para um usuário, enviando um código OTP para o celular cadastrado com base no documento informado.

Endpoint: POST /security/password/recover/challenge

Headers:

Content-Type: application/json

Request Body:

{
  "document": "12345678900"
}

Resposta de Sucesso (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 3
}

Possíveis Erros:

• 400 - Documento não encontrado ou formato inválido

5. Validar Desafio OTP de Recuperação

Valida o desafio OTP de recuperação

Valida o código OTP que o usuário recebeu (seja por SMS ou e-mail) para prosseguir com a recuperação.

Endpoint: POST /security/password/recovery/validate

Headers:

Content-Type: application/json

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456",
  "document": "12345678900"
}

Resposta de Sucesso (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 2
}

Possíveis Erros:

• 400 - Requisição inválida ou OTP incorreto

6. Efetuar Recuperação da Senha

Efetiva a recuperação da senha

Após a validação do OTP, este endpoint define a nova senha para o usuário.

Endpoint: POST /security/password/recovery

Headers:

Content-Type: application/json

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "credential": "NewStrongP@ssw0rd!"
}

Resposta de Sucesso (200):

• Senha recuperada e alterada com sucesso

Possíveis Erros:

• 400 - Requisição inválida (ex: token de validação OTP expirado ou senha fora do padrão)

7. Schemas de Dados

Modelos de Request e Response

OTPChangeCredentialResponse

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 3
}

ValidateOTPChangeCredentialRequest

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456",
  "document": "12345678900"
}

ChangeCredentialRequest

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "credential": "NewStrongP@ssw0rd!",
  "oldCredential": "OldP@ssw0rd123"
}

AuthenticationValidateResponse

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...",
  "refreshToken": "def502006a2c63c033a8a7a3f4c4a24a...",
  "expiresIn": 86400
}

ErrorResponse

{
  "timestamp": "2023-12-01T10:30:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Código OTP inválido",
  "path": "/security/password/recovery/validate"
}

8. Autenticação

Token de Autorização

Para endpoints protegidos, utilize o header:

X-BuildersBank-Authorization: {token_de_sessao}

Descrição: Token de sessão do usuário obtido no fluxo de login. Para os endpoints protegidos, este token deve ser válido e conter o escopo "accounts-consumer".

Servidor:

• Produção: https://api.buildersbank.com.br