​

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:

​

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