API Request Authentication

Partner APIs use API key authentication and Ed25519 request signatures. The merchant-redeem API uses a login token and ECDSA request signatures.

Credential Setup

When partner API access is created in the partner portal:

• The portal generates an Ed25519 keypair.
• The platform stores the public key in the API access record.
• The private key is shown once. Store it in your secret manager.

Partner Required Headers

Header	Required	Description
X-API-Key	Yes	API access credential.
X-Timestamp	Yes	ISO timestamp used in signature verification. Requests outside 5 minutes of server time are rejected.
X-Signature	Yes	Base64-encoded Ed25519 signature of the canonical string.
Idempotency-Key	Required on partner write POST endpoints	Retry key included in the canonical string.
X-Correlation-Id	Merchant API optional	Correlation value for multi-step tracing.
User-Agent	No	Optional client identifier.

Canonical String

Sign this exact UTF-8 string with your Ed25519 private key:

HTTP_METHOD
PATH
X-Timestamp
Idempotency-Key
base64(sha256(rawBody))

The canonical payload is the 5 lines above joined with newline characters (\n) in that exact order.

Canonical String Rules

• HTTP_METHOD must be uppercase, for example GET or POST.
• PATH must include the versioned path and query string when present.
• If your public URL includes /api, remove only that prefix in the canonical PATH.
  • Partner example request URL path: /api/v1/data-packages?page=1&limit=10
  • Partner canonical PATH: /v1/data-packages?page=1&limit=10
• Idempotency-Key must match the trimmed header value exactly. If not sent, use an empty line.
• rawBody must be the exact raw request bytes. For requests without a body, hash the empty string.
• X-Signature must be valid base64.

Merchant-Redeem Authentication

The merchant-redeem flow uses these credentials and headers:

Step	Credential or header	Description
Login	key request body field	Merchant API key sent to POST /api/v1/merchant/client/auth/login.
Authenticated calls	x-api-token	JWT access token returned by login.
Signed POST calls	x-signature	Base64 ECDSA P-256 SHA-256 signature over JSON.stringify(request body).

GET /api/v1/merchant/client/topup-transactions/:voucherCode requires x-api-token only. initiate-claim, redeem-gift, and redeem-gift/callback require both x-api-token and x-signature.

Partner Example Headers

X-API-Key: partner_live_xxxxxxxxxxxxx
X-Timestamp: 2026-04-29T12:00:00.000Z
X-Signature: BASE64_ED25519_SIGNATURE
Idempotency-Key: 8c9b3f8d-0f1a-4c6a-8e69-0f6c0a1e39c2