BigCity Authentication

Two-tier authentication system for companies and customers

Secure & Scalable Authentication

The BigCity API uses a two-tier authentication system where companies first authenticate to obtain access to the platform, then use their company token to authenticate individual customers.

Company Auth Customer Auth
Company
Token
Customer

Authentication Flow Overview

Company Authentication

Purpose: Platform access

Input: Company secret

Output: Company token

Lifetime: 24 hours

Uses company token

Customer Authentication

Purpose: Order operations

Input: Customer data

Output: Customer token

Lifetime: 24 hours

Step 1: Company Authentication

POST /v1/company/auth

API authentication for companies to access the BigCity rewards platform.

Headers

Header Value Description
Authorization Required Must be set to "Required"
Content-Type application/json Request content type

Parameters

Parameter Type Required Description
secret string Required The company secret key for authentication

Request Example

cURL
JavaScript
Python
curl -X POST https://api.bigcity.in/v1/company/auth \
  -H "Authorization: Required" \
  -H "Content-Type: application/json" \
  -d '{"secret": "your_company_secret_key"}'
const response = await fetch('https://api.bigcity.in/v1/company/auth', {
  method: 'POST',
  headers: {
    'Authorization': 'Required',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    secret: 'your_company_secret_key'
  })
});

const authData = await response.json();
import requests

response = requests.post(
    'https://api.bigcity.in/v1/company/auth',
    headers={
        'Authorization': 'Required',
        'Content-Type': 'application/json'
    },
    json={'secret': 'your_company_secret_key'}
)

auth_data = response.json()

Success Response

{
  "vendor_id": 1,
  "vendor_name": "BigCity",
  "vendor_company_name": null,
  "vendor_email": null,
  "vendor_company_email": "company@bigcity.in",
  "state": "Active",
  "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "created_at": "2025-10-10 15:28:12",
  "updated_at": "2025-10-10 11:24:42",
  "last_logged_in": "2025-10-10 13:47:16",
  "token_expiry": "2025-10-11 13:47:16",
  "credit_balance": "0"
}

Error Response

{
  "name": "Bad Request",
  "message": "Could not authenticate you",
  "code": 0,
  "status": 400,
  "type": "yii\\web\\HttpException"
}

Response Fields

Field Type Description
vendor_id integer Unique company identifier
vendor_name string Company display name
auth_token string JWT token for API access
token_expiry datetime Token expiration time
state string Account status (Active/Inactive)

Step 2: Customer Authentication

POST /v1/customer/auth

Authenticate individual customers using the company auth token to enable reward redemptions.

Headers

Header Value Description
Authorization Bearer {company_token} Company authentication token
Content-Type application/json Request content type

Parameters

Parameter Type Required Description
mobile_no string Required Customer mobile number
customer_name string Optional Customer full name
customer_email string Optional Customer email address

Request Example

cURL
JavaScript
Python
curl -X POST https://api.bigcity.in/v1/customer/auth \
  -H "Authorization: Bearer YOUR_COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "John Doe",
    "customer_mobile": "1234567890",
    "customer_email": "john@example.com"
  }'
const response = await fetch('https://api.bigcity.in/v1/customer/auth', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${companyToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_name: "John Doe",
    customer_mobile: "1234567890",
    customer_email: "john@example.com"
  })
});

const customerAuth = await response.json();
response = requests.post(
    'https://api.bigcity.in/v1/customer/auth',
    headers={
        'Authorization': f'Bearer {company_token}',
        'Content-Type': 'application/json'
    },
    json={
        'customer_name': 'John Doe',
        'customer_mobile': '1234567890',
        'customer_email': 'john@example.com'
    }
)

customer_auth = response.json()

Success Response

{
  "customer_id": 1,
  "customer_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_expiry": "2025-10-14 14:31:35"
}

Error Response

{
  "name": "Unprocessable entity",
  "message": "Enter Valid Input",
  "code": 0,
  "status": 422,
  "type": "yii\\web\\HttpException"
}

Token Management

Company Token

Used for: Customer authentication, rewards listing
Lifetime: 24 hours
Scope: Company-wide operations

Customer Token

Used for: Order creation, redemption operations
Lifetime: 24 hours
Scope: Customer-specific operations

Security Best Practices

Secure Storage

Store tokens securely with encryption at rest

Never Expose

Never expose tokens in client-side code or logs

Token Rotation

Implement token refresh before expiry

HTTPS Only

Always use HTTPS for token transmission

Error Handling

400

Bad Request

Cause: Invalid credentials or malformed request

Solution: Verify request format and credentials

401

Unauthorized

Cause: Invalid or expired token

Solution: Re-authenticate to get new token

422

Unprocessable Entity

Cause: Validation failed

Solution: Check required fields and data types

429

Too Many Requests

Cause: Rate limit exceeded

Solution: Implement exponential backoff

Error Response Format

{
  "name": "Error Type",
  "message": "Human readable error message",
  "code": 0,
  "status": 400,
  "type": "yii\\web\\HttpException"
}