API Request Authentication

Partner and merchant server-to-server requests use API key authentication and Ed25519 request signatures.

Credential Setup

When API access is created in the partner or merchant 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.

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 and merchant redeem 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 that prefix in the canonical PATH.
  Example request URL path: /api/v1/data-packages?page=1&limit=10
  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.

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