Authentication Models

The Partner portal uses API key + HMAC-SHA256 authentication exclusively. There is no JWT, no Secure Channel, and no browser session model for Partner API integrations.

API Key Authentication

Every request to /api/v1/partner/** must include these headers:

Header	Description
X-Api-Key	Your provisioned API key
Authorization	HMAC-SHA256 <signature>
X-Timestamp	Unix epoch seconds (must be within ±60s of server time)
X-Nonce	Unique per-request identifier (UUID recommended)

Signature Construction

stringToSign = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + BODY
signature   = Base64(HMAC-SHA256(apiSecret, stringToSign))

Walkthrough

1. Concatenate the five components with newline separators
2. Compute HMAC-SHA256 using your API secret as the key
3. Base64-encode the resulting binary digest
4. Place the result in the Authorization header as HMAC-SHA256 <signature>

Example (GET, no body)

METHOD    = GET
PATH      = /api/v1/partner/constants/countries
TIMESTAMP = 1709337600
NONCE     = 550e8400-e29b-41d4-a716-446655440000
BODY      = (empty string)

stringToSign = "GET\n/api/v1/partner/constants/countries\n1709337600\n550e8400-e29b-41d4-a716-446655440000\n"

Replay Protection

• Timestamp: Requests with a timestamp older than 60 seconds are rejected (GA2013)
• Nonce: Each nonce may only be used once; reuse is rejected (GA2014)
• Generate a fresh nonce (e.g. UUID v4) for every request

API Key Lifecycle

Action	Endpoint
Create	POST /web/v1/partner/api-keys (via portal UI)
List	GET /web/v1/partner/api-keys
Disable	POST /web/v1/partner/api-keys/{id}/disable
Enable	POST /web/v1/partner/api-keys/{id}/enable
Delete	DELETE /web/v1/partner/api-keys/{id}

Common Errors

Code	Cause
GA2001	Missing X-Api-Key
GA2002	Missing X-Signature
GA2003	Missing X-Timestamp
GA2004	Missing X-Nonce
GA2011	API key invalid or not found
GA2012	Signature verification failed
GA2013	Timestamp outside validity window
GA2014	Nonce already used
GA2021	API key disabled
GA2022	IP not in whitelist