SDK Authentication

Coming Soon

This feature is under active development and not yet available. The API endpoints, SDK packages, and behavior described here are subject to change before release.

The Bill Presentment SDK uses existing B2B API Key + HMAC authentication for session creation, then a single session_token for SDK API calls.

Overview

Authentication involves two parties:

Party	Authenticates With	Purpose
Client backend	X-Api-Key + HMAC headers	Create SDK sessions (POST /v2/sdk/sessions)
SDK WebView (hosted app)	Authorization: Bearer {session_token}	Fetch bills and outstanding amounts

INFO

There is no separate client_id/client_secret flow, no SDK-specific secret rotation, and no POST /v2/sdk/token exchange endpoint.

API Key + HMAC Authentication

Session creation uses the same authentication scheme as other B2B API key endpoints.

Required headers:

• X-Api-Key
• X-Timestamp
• X-Nonce
• X-Signature (v1=...)

Request body for POST /v2/sdk/sessions:

{
  "ic_number": "901234567890",
  "name": "John Tan",
  "email": "john@example.com",
  "phone": "+60123456789",
  "address": "Kuala Lumpur"
}

• ic_number is required
• name, email, phone, and address are optional

DANGER

HMAC signing must be done on your backend only. Never expose API keys or HMAC secrets in frontend or mobile code.

Session Flow

Session Token

Property	Value
Format	bp_sess_xxxx (prefixed random token)
TTL	15 minutes sliding (extended on each API call)
Absolute max lifetime	1 hour
Delivery transport	URL fragment (#token=...)
API transport	Authorization: Bearer {session_token}

Single-use delivery behavior:

1. SDK wrapper opens bills.iimmpact.com/#token=...
2. Hosted app reads token from location.hash
3. Hosted app clears the fragment immediately
4. All subsequent auth uses Authorization header only

Session Lifecycle

IC Number Handling

IC number handling is split by storage purpose:

• Redis session data: stores plaintext ic_number short-term for session-bound processing inside VPC-internal infrastructure
• PostgreSQL lookup: uses hashed IC value for user/account matching
• API responses/logs: never return IC number in SDK API responses; sensitive fields should not be logged

INFO

Plaintext IC storage is intentionally short-lived and limited to Redis session scope.

Bill Set Validation

GET /v2/sdk/outstanding is constrained by the bill set loaded for the active session:

1. GET /v2/sdk/bills computes eligible bill pairs for the user
2. API stores those valid pairs in Redis under the session
3. Each GET /v2/sdk/outstanding request is validated against that Redis set
4. Requests for pairs outside the session bill set are rejected

This prevents arbitrary account probing with a valid session_token.

Security Considerations

Concern	Mitigation
Session creation abuse	Authenticated with existing X-Api-Key + HMAC validation
Token leakage in URLs	Delivery via URL fragment, then fragment cleared after read
Token replay window	Short token lifetime (15 min sliding, 1 hour absolute max)
Unauthorized outstanding lookup	Bill pair must exist in Redis bill set for the active session
IC number exposure	Plaintext IC only in short-lived Redis session data; hashed for PostgreSQL lookup
Cross-origin embedding	CORS allows all origins; access still requires valid scoped session_token