Developer guide · API security
Choose the loyalty API credential that matches the caller.
Signed-in user roles and machine integrations have different credentials. Choose the interface first, then narrow the role, permission, scope, and secret exposure.
- Signed-in caller
- Session bearer token
- Machine caller
- Long-lived Agent key
- Authorization
- Role, scope, and ownership
Short answer
Choose credentials from the caller.
Reward Loyalty has two current REST authentication roles. The session-token REST API logs in a signed-in administrator, partner, staff member, or member and sends that role token as a Bearer token on role-specific routes. The Agent API authenticates a machine caller with a long-lived key in the X-Agent-Key header. Its current contract is key-based, with no OAuth grant flow. The owner role, feature permission, scopes, resource ownership, key status, expiry, and rate policy still limit each request.
Decision criteria
Authenticate the role before authorizing the task.
A signed-in user session and a long-running machine process need different credentials, exposure limits, and revocation paths.
Caller identity
Use the session-token API when a person signs in as a product role. Use the Agent API when a trusted service must call without a human session.
Privilege size
Choose the owner role first, then the smallest scopes and feature access that cover the task. A broad credential cannot compensate for unclear integration ownership.
Secret lifecycle
Decide where the credential is created, shown, stored, rotated, revoked, audited, and removed before building the first business request.
Credential choice
Do not mix user sessions and machine keys.
Both interfaces use HTTPS and JSON, but their identity and lifecycle contracts differ.
Session-token REST API
A role-specific login issues a token for the signed-in administrator, partner, staff member, or member. The client sends the Bearer token to that role route and logs out or clears it under the session workflow.
Agent API
An administrator, partner, or registered member can own a long-lived Agent key under the current rules. A trusted service sends the full secret through X-Agent-Key on the role-matched Agent route.
Browser and mobile boundary
Use signed-in user credentials for user-facing clients. Keep partner and administrator Agent keys on a trusted server; do not embed a broad machine key in JavaScript, a mobile binary, or a public automation URL.
OAuth boundary
The Agent API uses key authentication in the current implementation. No OAuth authorization-code, client-credentials, refresh-token, or delegated-consent flow should be inferred from API documentation tooling.
Secret lifecycle
Plan creation through revocation.
The full Agent secret has a one-time display and cannot be recovered from the stored hash.
-
1
Create
Name the integration, select the owner and least-privilege scopes, set an expiry where suitable, and generate the key through the current role interface.
-
2
Capture once
Copy the full secret during its one-time reveal into a secret manager. Reward Loyalty retains a display prefix and a password-style hash, not a retrievable full key.
-
3
Operate
Track the key prefix, integration owner, purpose, deployment, scopes, expiry, last use, rate behavior, and activity records without logging the full secret.
-
4
Rotate or revoke
Create and deploy a replacement before disabling the old key when continuity matters. Revocation marks the old key inactive and keeps its record available for authentication and audit history.
Production controls
Test denial and uncertain writes.
A successful health request proves the credential path, not the safety of every business operation.
Authentication tests
Exercise missing, malformed, wrong, expired, revoked, wrong-role, inactive-owner, and feature-disabled cases. Verify that clients stop or escalate instead of retrying permanent denials.
Scope and ownership tests
Call one allowed read, one denied write, and one foreign-resource request. Confirm that the integration treats absence and denial without leaking record details.
Rate and audit tests
Observe the current per-key rate headers, handle rate responses with backoff, and confirm successful authenticated requests produce the expected audit activity without exposing the secret.
Write recovery
Use validation errors to correct a request. For a timeout or unknown outcome on a non-idempotent purchase, redemption, or deduction, reconcile current state before retrying.
Product and operating limits
Authentication does not grant every operation.
- The current Agent API authentication contract is X-Agent-Key, not OAuth. The session-token REST API and Agent API are separate interfaces and their tokens are not interchangeable.
- A valid key does not bypass feature settings, partner permission, role, scope, ownership, validation, rate, or business rules.
- Reward Loyalty stores Agent key hashes and audit evidence. The installation operator still owns HTTPS, secret management, backups, log access, incident response, credential rotation, and custom client security.
Implementation guides
Use current documentation for changing details.
Requirements, interfaces, settings, limits, and release behavior belong in the maintained product documentation.