Skip to main content

Authentication and security

FieldValue
Backend authenticationAPI Key
HeaderX-Api-Key
ScopeSend the header on every request
Test base URLhttps://api-integration.test.kaizenloyalty.com/api/v1
Rate limit300 requests per minute per API key
Frontend SDK authenticationChallenge token + customer JWT

See Environments for the available base URLs.

Choose an authentication method​

Integration typeMechanismCredential owner
Backend-to-Backend Integration APIX-Api-KeyServer-side integrating application
Frontend/Mobile SDKx-challenge-token + Authorization: Bearer <JWT>KLP application challenge + customer IdP

Backend API key authentication​

Send the API key header on every request to the Integration API:

X-Api-Key: <YOUR_API_KEY>
Content-Type: application/json

Never keep the API key in a browser, a mobile binary, a public repository, a support ticket, or client-side JavaScript.

Create an API key​

  1. In the KLP/PAL panel, open ApplicationDetail / Settings.
  2. Select API Keys.
  3. Click Generate New API Key.
  4. Enter a name for the key.
  5. Choose whether the key needs write access.
  6. Create the key and save it in a secure secret store.

The key is displayed only once. If you lose it, create a new key.

Permissions​

Key configurationAccess
Write access offGET endpoints only
Write access onPOST, PUT, DELETE and GET integration operations

The error body returned for a request with insufficient permission is not documented; contract-test the actual response before going to production.

Error contract​

Missing header​

HTTP/1.1 401 Unauthorized

The response body is empty.

Invalid API key​

HTTP/1.1 404 Not Found
Content-Type: application/json
{
"Code": 3001,
"Message": "Code:3001, Message:Code:3001, Message:Api Key could not be found!"
}

Generate telemetry from the Code field when it is present, not only from the HTTP status. Do not show the error message directly to end users.

Rate limit​

HTTP/1.1 429 Too Many Requests

The limit is 300 requests per minute per API key.

The Retry-After header and the response body are not documented. Use the following approach in your client:

  • If Retry-After is present, honor it.
  • Otherwise, apply exponential backoff with jitter.
  • Do not retry checkout requests indefinitely.
  • Monitor the rate-limit metric per application and per API key.

Gateway validation flow​

Backend Service
│ X-Api-Key
▼
KLP Integration Gateway
├── Header existence
├── Key lookup
├── Expiration
├── Application/environment binding
├── Read/write access
└── Per-key rate limit
▼
KLP APIs

API key lifecycle​

Recommended operating model:

  • Use separate applications and keys for Sandbox and Production.
  • Generate a separate key for each integrating service.
  • Keep key owner, purpose, permission and expiration metadata in your secret inventory.
  • Rotate keys periodically.
  • During rotation, run the old and new keys in parallel for a controlled transition period.
  • If you suspect a key is compromised, revoke it and review the audit logs.
  • Redact the key value in logs, traces, exceptions and APM tags.

Network and transport security​

Responses are served over HTTPS with an HSTS header. Production standard:

  • Use HTTPS only.
  • Do not disable TLS certificate validation.
  • Use connection pooling.
  • Test DNS and TLS handshake failure scenarios.
  • Verify that your proxy/WAF does not log the X-Api-Key header.
  • Prevent the API key from being moved into the query string.

Frontend SDK dual-token model​

In a frontend SDK integration, the application and the user are authenticated with different credentials. The SDK authenticates with a challenge token together with the user's JWT. See the mobile SDK guides for integration details.

Application identity​

x-challenge-token: <challenge_token>

User identity​

Authorization: Bearer <customer_jwt>

Minimum JWT payload example:

{
"sub": "user-123"
}

The user identifier claim is configured per application:

{
"authenticationType": "JwtPublicKey",
"userIdField": "sub"
}

Use an immutable user identifier rather than a mutable email address.

SDK request signing (non-GET requests)​

Pending verification

Every request that does not carry X-Api-Key (that is, every request coming through the SDK) and is not a GET must also be signed:

X-Nonce: <nonce>
X-Timestamp: <unix_timestamp>
X-Signature: <signature>
  • The SDK produces the signature itself using the KLP SDK credential. The integrating application must not produce signatures manually.
  • If any of these headers is missing: 400, "Message": "400_MissingHeaderValue".
  • If the signature cannot be validated: 400, "Message": "400_ValidationFailed".

SDK error codes​

ConditionHTTPMessage
X-Challenge-Token missing401401_Challenge
Challenge token could not be validated401401_Challenge
Signature header missing (non-GET)400400_MissingHeaderValue
Signature invalid (non-GET)400400_ValidationFailed

Current-consumer (/me) endpoints​

In SDK requests, the consumer identity is resolved from the configured claim in the JWT. For this reason, the SDK uses the /me variants instead of endpoints that carry integrationId in the path. For the full list, see Current-consumer endpoints in Consumers, wallets and goals.

  • /me endpoints work only with SDK authentication. X-Api-Key requests have no current-consumer identity; your backend must always use the endpoints that take an integrationId.
  • If an SDK request sends an integrationId in the path, query or body that differs from the user in the JWT, the API returns 403 Forbidden (Integration Id cannot be different from current integration user.). A user cannot access another consumer's data.
  • The gateway discards any identity headers supplied by clients on every request, so a client cannot impersonate another consumer.

Frontend validation flow​

SDK / Frontend
├── Challenge request
├── Challenge verification
└── Challenge token

Customer Login
└── Customer IdP JWT

Authenticated Request
├── x-challenge-token
└── Authorization: Bearer <JWT>

KLP Identity Service
├── Validate challenge token
├── Resolve application
├── Validate JWT signature/public key
├── Validate token dates
├── Extract configured claim
└── Authorize downstream request

Security controls​

  • Asymmetric JWT signature validation
  • Challenge-response authentication
  • Public-key verification
  • Expiration validation
  • Nonce/replay protection
  • Application signature validation
  • SDK/application version validation
  • API key least privilege
  • Per-key rate limiting
  • Environment isolation
  • Secret rotation
  • Structured audit logging

Logging and redaction​

Do not log:

  • API key
  • Customer JWT
  • Challenge token
  • Coupon/voucher/referral code
  • Full consumer PII
  • Raw authentication headers

Safe fields to log:

  • Environment/application name
  • Correlation ID
  • HTTP status
  • Internal error code (such as 3001)
  • Endpoint template
  • Latency
  • Rate-limit count

Production checklist​

  • HTTPS is enforced.
  • Test and Production base URLs are separated.
  • Sandbox and Production keys are separated.
  • Write access is verified for write endpoints.
  • The API key is stored in a secret manager.
  • Key log redaction is active.
  • The key rotation runbook has been tested.
  • The missing key 401 test has been run.
  • The invalid key 404 / Code 3001 test has been run.
  • The insufficient-permission response contract has been verified.
  • The 300 requests/minute limit has been verified with a load test.
  • A 429 retry policy is in place.
  • The SDK JWT public key and user claim configuration have been tested.
  • Token expiry, invalid signature and replay negative tests are complete.

For the full pre-launch list, see Production checklist.