​
B2C Customer Authentication Flow

This guide details the complete authentication flow for individual (B2C) customers in the FinHub platform. The authentication process involves token generation, retrieving customer details, and two-factor authentication when enabled.

​
Flow Overview

The following sequence diagram illustrates the complete B2C authentication process:

​
Detailed API Flow

​
Step 1: Generate Authentication Token

The first step is to authenticate the user and generate the necessary tokens. API Request: 
POST /api/v2/auth/token
Content-Type: application/json
Request Body: 
{
  "username": "john.doe@example.com",
  "password": "SecureP@ssw0rd",
  "accountType": "B2C"
}
Response: 
{
  "bffToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "sess_12345678",
  "customerId": "cust_12345678",
  "expiresIn": 3600
}
Implementation Notes:
  • The tokens are stored in localStorage
  • The bffToken is used for subsequent API calls
  • The session has an expiration time (typically 1 hour)
  • The system records the login attempt for security monitoring

​
Step 2: Get Customer Details

After authentication, the system retrieves the customer’s profile details. API Request: 
POST /api/v2/customer/details
Content-Type: application/json
Authorization: Bearer {bffToken}
Request Body: 
{
  "customerId": "cust_12345678"
}
Response: 
{
  "customerId": "cust_12345678",
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "nationality": "United States",
    "phoneNumber": "+12125551234"
  },
  "status": "ACTIVE",
  "kycStatus": "VERIFIED",
  "twoFactorEnabled": true,
  "createdAt": "2025-05-15T10:30:00Z",
  "lastLoginAt": "2025-06-01T09:15:00Z"
}
Implementation Notes:
  • The customer details are stored in the application state
  • The response includes the KYC status and 2FA settings
  • The system updates the last login timestamp

​
Step 3: Two-Factor Authentication (if enabled)

If 2FA is enabled for the customer, an additional verification step is required. API Request to initiate 2FA: 
POST /api/v2/auth/2fa/initiate
Content-Type: application/json
Authorization: Bearer {bffToken}
Request Body: 
{
  "customerId": "cust_12345678",
  "method": "SMS" // or "EMAIL", "AUTHENTICATOR"
}
Response: 
{
  "verificationId": "ver_87654321",
  "method": "SMS",
  "sentTo": "+1*****1234",
  "expiresAt": "2025-06-01T09:25:00Z"
}
API Request to verify 2FA code: 
POST /api/v2/auth/2fa/verify
Content-Type: application/json
Authorization: Bearer {bffToken}
Request Body: 
{
  "customerId": "cust_12345678",
  "verificationId": "ver_87654321",
  "code": "123456"
}
Response: 
{
  "status": "VERIFIED",
  "message": "Two-factor authentication successful",
  "sessionExtended": true,
  "newExpiresAt": "2025-06-01T11:15:00Z"
}
Implementation Notes:
  • The 2FA code is typically a 6-digit number
  • The code is valid for a limited time (usually 10 minutes)
  • After successful 2FA verification, the session expiration is extended
  • The system records the successful 2FA verification for security monitoring

​
Logout Process

The logout process invalidates the current session and clears authentication data. API Request: 
POST /api/v2/auth/logout
Content-Type: application/json
Authorization: Bearer {bffToken}
Request Body: 
{
  "sessionId": "sess_12345678"
}
Response: 
{
  "status": "SUCCESS",
  "message": "Successfully logged out"
}
Implementation Notes:
  • The system invalidates the session on the server
  • All localStorage items are cleared
  • The application state is reset
  • The user is redirected to the login page

​
Error Handling

The authentication process includes comprehensive error handling for various scenarios:
Error ScenarioError CodeDescription
Invalid credentialsINVALID_CREDENTIALSThe provided username or password is incorrect
Account lockedACCOUNT_LOCKEDThe account has been locked due to too many failed attempts
Session expiredSESSION_EXPIREDThe authentication session has expired
Invalid 2FA codeINVALID_2FA_CODEThe provided 2FA code is incorrect
Expired 2FA code2FA_CODE_EXPIREDThe 2FA code has expired
Too many 2FA attemptsTOO_MANY_2FA_ATTEMPTSToo many failed 2FA verification attempts

​
Security Considerations

When implementing the B2C authentication flow, consider the following security measures:
  1. Rate Limiting: Implement rate limiting to prevent brute force attacks
  2. IP Tracking: Monitor and flag suspicious login attempts from unusual locations
  3. Device Fingerprinting: Track and verify device information for additional security
  4. Session Management: Implement proper session timeout and renewal mechanisms
  5. Secure Communication: Ensure all authentication traffic is encrypted with TLS
  6. Audit Logging: Maintain detailed logs of all authentication activities

​
Next Steps

After successful authentication, the customer can:
  1. Access their dashboard
  2. View their accounts
  3. Initiate transactions
  4. Manage their profile