Jornada de Autenticação e Associação de Dispositivo
Diagrama do Fluxo
Representação documental dos fluxos de autenticação e de associação de dispositivo, baseada nos passos descritos nesta jornada. A entrega do OTP ao usuário (SMS/e-mail) está documentada nos passos de challenge.
Esta documentação apresenta os dois processos principais da API Finway Security: a autenticação de usuários e a associação de dispositivos. Cada processo é independente e tem seus próprios endpoints específicos.
Jornada de Autenticação
O processo de autenticação permite que usuários façam login na plataforma usando CPF e senha.
Origem dos Dados
- Senha (credential): Criada pelo usuário durante o processo de onboarding/registro inicial
- DeviceIdentification: Gerado pelo aplicativo cliente (ex: "iOS-iPhone-12", "DEVICE_INFO")
Visão Geral do Fluxo de Autenticação
O fluxo de autenticação consiste em 2 etapas:
- Challenge de Autenticação - Iniciar processo de autenticação com CPF
- Validar Credenciais - Validar senha e obter tokens de acesso
Passo 1: Challenge de Autenticação
POST /api/bank-services/security/authentication/challenge
Inicia o processo de autenticação criando um desafio de autenticação para um usuário a partir do seu CPF.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
Request Body
{
"cpf": "12345678900",
"deviceIdentification": "DEVICE_INFO"
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cpf | string | Sim | CPF do usuário |
deviceIdentification | string | Não | Identificação do dispositivo (opcional) |
Response (200)
{
"challenge": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"types": ["PASSWORD"]
}
Possíveis Erros
- 400 Bad Request - Requisição inválida (ex: CPF mal formatado)
- 404 Not Found - Usuário não encontrado
Passo 2: Validar Credenciais de Autenticação
POST /api/bank-services/security/authentication/validate
Valida o desafio com a credencial do usuário (senha) para obter os tokens de acesso.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
Request Body
{
"challenge": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"type": "PASSWORD",
"credential": "MySecretPassword123"
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
challenge | string | Sim | Token do desafio recebido na etapa anterior |
type | string | Sim | Tipo de credencial sendo enviada |
credential | string | Sim | A senha do usuário |
Response (200)
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...",
"refreshToken": "def502006a2c63c033a8a7a3f4c4a24a...",
"expiresIn": 86400
}
Possíveis Erros
- 400 Bad Request - Requisição inválida (ex: desafio expirado)
- 401 Unauthorized - Não autorizado (senha incorreta)
Jornada de Associação de Dispositivo
O processo de associação de dispositivo permite vincular um dispositivo a um usuário através de validações por SMS e Email.
Visão Geral do Fluxo de Associação
O fluxo de associação de dispositivo consiste em 5 etapas:
- Gerar Challenge SMS - Envio de código OTP via SMS
- Validar OTP SMS - Validação do código recebido por SMS
- Gerar Challenge Email - Envio de código OTP via Email
- Validar OTP Email - Validação do código recebido por Email
- Finalizar Associação - Confirmação final da associação do dispositivo
Passo 1: Gerar Challenge SMS para Associação de Dispositivo
POST /api/bank-services/security/device/sms/otp/challenge
Gera um código OTP via SMS para o processo de associação de dispositivo. O usuário receberá um código no telefone cadastrado.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
x-buildersbank-authorization | Sim | Token de autenticação da API |
Request Body
{
"cpf": "12345678901"
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cpf | string | Sim | CPF do usuário (apenas números) |
Response (200)
{
"token": "temp_validation_token",
"phone": "11987654321",
"route": "SMS"
}
Possíveis Erros
- 400 Bad Request - Dados de entrada inválidos
- 401 Unauthorized - Token de autenticação inválido ou ausente
- 500 Internal Server Error - Erro interno do servidor
Passo 2: Validar OTP SMS para Associação de Dispositivo
POST /api/bank-services/security/device/sms/otp/validate
Valida o código OTP recebido via SMS para completar a primeira etapa da associação do dispositivo.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
x-buildersbank-authorization | Sim | Token de autenticação da API |
Request Body
{
"token": "temp_validation_token",
"cpf": "12345678901",
"code": "123456"
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
token | string | Não | Token temporário do processo |
cpf | string | Sim | CPF do usuário (11 dígitos) |
code | string | Sim | Código OTP de 6 dígitos |
Response (200)
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"route": "DEVICE_ASSOCIATED"
}
Possíveis Erros
- 400 Bad Request - Código OTP inválido ou expirado
- 401 Unauthorized - Token inválido
- 500 Internal Server Error - Erro interno do servidor
Passo 3: Gerar Challenge Email para Associação de Dispositivo
POST /api/bank-services/security/device/mail/otp/challenge
Gera um código OTP via email para o processo de associação de dispositivo. O usuário receberá um código no email cadastrado.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
x-buildersbank-authorization | Sim | Token de autenticação da API |
Request Body
{
"cpf": "12345678901",
"token": "temp_validation_token",
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cpf | string | Sim | CPF do usuário (apenas números) |
Response (200)
{
"token": "temp_validation_token",
"email": "user@example.com",
"route": "EMAIL"
}
Possíveis Erros
- 400 Bad Request - Dados de entrada inválidos
- 401 Unauthorized - Token de autenticação inválido ou ausente
- 500 Internal Server Error - Erro interno do servidor
Passo 4: Validar OTP Email para Associação de Dispositivo
POST /api/bank-services/security/device/mail/otp/validate
Valida o código OTP recebido via email para completar a segunda etapa da associação do dispositivo.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
x-buildersbank-authorization | Sim | Token de autenticação da API |
Request Body
{
"token": "temp_validation_token",
"cpf": "12345678901",
"code": "123456"
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
token | string | Não | Token temporário do processo |
cpf | string | Sim | CPF do usuário (11 dígitos) |
code | string | Sim | Código OTP de 6 dígitos |
Response (200)
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"route": "DEVICE_ASSOCIATED"
}
Possíveis Erros
- 400 Bad Request - Código OTP inválido ou expirado
- 401 Unauthorized - Token inválido
- 500 Internal Server Error - Erro interno do servidor
Passo 5: Validar Associação de Dispositivo
POST /api/bank-services/security/device/validate
Finaliza o processo de associação do dispositivo após validação dos OTPs de SMS e Email.
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | Sim | application/json |
x-buildersbank-authorization | Sim | Token de autenticação da API |
Request Body
{
"cpf": "12345678901",
"token": "temp_validation_token",
"deviceKey": "device_public_key",
"deviceIdentification": "meu-device-123"
}
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cpf | string | Sim | CPF do usuário (apenas números) |
token | string | Não | Token temporário do processo |
deviceKey | string | Não | Chave pública do dispositivo |
deviceIdentification | string | Não | Identificação do dispositivo |
Response (200)
{
"message": "Dispositivo associado com sucesso"
}
Possíveis Erros
- 400 Bad Request - Dados de entrada inválidos
- 401 Unauthorized - Token inválido ou processo não completado
- 500 Internal Server Error - Erro interno do servidor
Esquemas de Dados
AuthenticationChallengeRequest
{
"cpf": "string",
"deviceIdentification": "string (opcional)"
}
AuthenticationChallengeResponse
{
"challenge": "string (uuid)",
"types": ["string"]
}
AuthenticationValidateRequest
{
"challenge": "string (uuid)",
"type": "string",
"credential": "string (password)"
}
AuthenticationValidateResponse
{
"accessToken": "string (JWT)",
"refreshToken": "string",
"expiresIn": "integer"
}
DeviceAssociationRequest
{
"cpf": "string (11 dígitos)",
"token": "string (opcional)",
"deviceKey": "string (opcional)",
"deviceIdentification": "string (opcional)",
"externalDeviceId": "string (opcional)"
}
ValidateOTPRequest
{
"token": "string (opcional)",
"document": "string (11 dígitos)",
"code": "string (6 dígitos)"
}
DeviceAssociationResponse
{
"token": "string",
"email": "string (opcional)",
"phone": "string (opcional)",
"accessToken": "string (opcional)",
"route": "SMS | EMAIL | DEVICE_ASSOCIATED"
}