Administrator API access

Authenticate as an admin to perform privileged actions via the WLL API using an admin access token.

Admin API access allows you to authenticate as an administrator and perform privileged operations in the WLL platform — such as adjusting user points, managing rewards, or retrieving reports.

To use admin access, you must include both your API key and a valid admin access token in each request.

---

When to use admin access

Admin access is required for any operation that falls outside a single end user’s scope or requires elevated permissions.

Common use cases include:

• Adjusting a user’s points balance

• Managing rewards or incentives

• Viewing user activity across the program

• Performing reporting or data export operations

• Running scripts or automation via back-end services

---

Authentication method

Include both of the following headers in your request:

X-Api-Key: your-tenant-api-key
Authorization: Bearer admin-access-token

Your API key can be found in the Loyalty Console > Settings > Tenant screen.

---

Generating admin access tokens

You must first request your client credentials (client ID and secret) using the instructions in Request API credentials. These are then used to generate short-lived OAuth2 tokens via the client credentials grant flow.

For step-by-step instructions, see Generate an admin access token.

Tokens are scoped to specific environments (e.g. staging or production) and only valid for operations your client credentials are authorized to perform.

Don't generate a new token for every API call

Admin access tokens are valid for 24 hours. You should generate a token once, cache it securely, and reuse it for all admin API requests during that window.

Requesting a new token for every call is unnecessary and inefficient — it creates unnecessary load and may result in throttling or extra usage costs.

---

Admin authentication flows

Admin authentication in WLL is based on OAuth2 tokens generated by WLL’s own identity and access management service. There are two supported ways to obtain an admin access token:

1. Non-interactive (server-to-server)

Use this for scripts, back-end services, or integrations.

• Based on OAuth2 client credentials grant

• Token is requested programmatically using client ID and secret

• Most common method for WLL integrations

• If you operate a multi-tenant scheme, the credentials can also be granted access to multiple tenants

See Generate an admin access token for the full request structure.

2. Interactive (Loyalty Console login)

Used when a staff member logs into the Loyalty Console and performs actions manually.

• Staff log in using their WLL account (email + password or SSO)

• A short-lived admin token is issued for API requests made through the Console

• Optional support for TOTP and external IdPs (e.g. Azure AD, Okta, Google Workspace, PingFederate)

Optional admin SSO flow

---

Permissions and scopes

Admin access tokens are scoped to fine-grained permissions. For example, permissions for managing Users include:

• create:users

• read:users

• update:user

• delete:users

Tokens only allow access to the operations your client credentials or admin role has been granted. If a request is rejected, check the permission scope and the environment the token was issued for.

Granting permissions to a staff member in the Loyalty Console

---

Security considerations

• Never expose client credentials or admin access tokens in front-end code

• Admin tokens should be short-lived and stored securely

• If you lose access to your credentials, contact WLL Support immediately

---

Next steps

• Request API credentials – to get your client ID and secret

• Generate an admin access token – to make your first authenticated request