Authentication

Authentication Flow

The Bigcity Microsite uses a two-step authentication process combining Customer ID validation and OTP verification.

Note: The authentication APIs below are hosted by the Client System. Bigcity Microsite calls these endpoints to generate and verify OTPs.

Step 1: Customer Enters Unique ID

Customer accesses the microsite and enters their assigned Customer Unique ID.

Customer ID: CUST12345

Step 2: Generate OTP

Microsite sends Customer ID to Client API. Client validates the Customer ID, generates OTP, and sends it to the registered mobile number.

POST /api/v1/auth/generate-otp
Authorization: Basic <base64(username:password)>
Content-Type: application/json

{
  "customer_id": "CUST12345"
}

Step 3: Verify OTP

Customer enters OTP. Microsite calls Client OTP Verification API. Upon successful verification, customer is authenticated with JWT token and points information.

POST /api/v1/auth/verify-otp
Authorization: Basic <base64(username:password)>
Content-Type: application/json

{
  "customer_id": "CUST12345",
  "otp": "123456",
  "reference_id": "REF123456"
}

Step 4: Session Creation

Bigcity Microsite creates customer session using returned JWT token. The customer is redirected to the dashboard.

Basic Authentication

All Client API requests require Basic Authentication in the HTTP header.

Authorization: Basic <credentials>

Where <credentials> is the Base64 encoding of username:password.

Example: For username bigcity and password secret123:

Authorization: Basic YmlnY2l0eTpzZWNyZXQxMjM=

JWT Authentication

After successful OTP verification, a JWT token is returned. This token must be included in all subsequent API requests.

Authorization: Bearer <jwt-token>

OTP Rules

  • Validity: 5 minutes
  • Maximum retry attempts: 3
  • OTP must expire after successful use
  • OTP generation is managed by the Client System
  • OTP validation is managed by the Client System

Customer Authentication Rules

  • Customer login is based on Customer Unique ID
  • OTP validation is mandatory
  • Session token (JWT) is issued after successful verification

Security

All APIs must use HTTPS (TLS 1.2 or above). JWT-based authentication is used for session management.