Authentication and security
| Field | Value |
|---|---|
| Backend authentication | API Key |
| Header | X-Api-Key |
| Scope | Send the header on every request |
| Test base URL | https://api-integration.test.kaizenloyalty.com/api/v1 |
| Rate limit | 300 requests per minute per API key |
| Frontend SDK authentication | Challenge token + customer JWT |
See Environments for the available base URLs.
Choose an authentication method
| Integration type | Mechanism | Credential owner |
|---|---|---|
| Backend-to-Backend Integration API | X-Api-Key | Server-side integrating application |
| Frontend/Mobile SDK | x-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
- In the KLP/PAL panel, open
ApplicationDetail / Settings. - Select
API Keys. - Click
Generate New API Key. - Enter a name for the key.
- Choose whether the key needs write access.
- 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 configuration | Access |
|---|---|
| Write access off | GET endpoints only |
| Write access on | POST, 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-Afteris 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-Keyheader. - 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)
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
| Condition | HTTP | Message |
|---|---|---|
X-Challenge-Token missing | 401 | 401_Challenge |
| Challenge token could not be validated | 401 | 401_Challenge |
| Signature header missing (non-GET) | 400 | 400_MissingHeaderValue |
| Signature invalid (non-GET) | 400 | 400_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.
/meendpoints work only with SDK authentication.X-Api-Keyrequests have no current-consumer identity; your backend must always use the endpoints that take anintegrationId.- If an SDK request sends an
integrationIdin the path, query or body that differs from the user in the JWT, the API returns403 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
401test has been run. - The invalid key
404 / Code 3001test has been run. - The insufficient-permission response contract has been verified.
- The 300 requests/minute limit has been verified with a load test.
- A
429retry 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.