User API access

How to authenticate API requests on behalf of a logged-in user using a user access token.

User API access allows you to make authenticated API requests on behalf of a specific end user. This is used whenever the request involves personalized data or actions, such as viewing a user’s points balance or reporting an event.

To use user access, you’ll need to pass a valid user access token in addition to your API key.

This article explains how to authenticate API requests on behalf of a user when using the WLL API directly.

If you’re looking for information on how user login works for the WLL Loyalty Microsite, see 2. Microsite authentication instead.

---

When to use user access

Use user authentication when:

• Reporting events

• Fetching a user’s wallet or user-specific reward list

• Redeeming a reward for a specific user

• Accessing any user-specific data or actions

---

Authentication method

To authenticate on behalf of a user, include both headers in your request:

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

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

---

Generating user access tokens

WLL does not issue user access tokens directly. You must generate tokens via your own identity provider (IdP), such as:

• Firebase Auth

• Auth0

• Any OIDC-compliant service

WLL validates JWTs signed by your IdP, based on your configured authentication settings.

Token requirements

Your user tokens must meet the following criteria:

• Format: JWT (per RFC 7519)

• Algorithms: RS256 (RSASSA-PKCS1-v1_5 with SHA-256) or HS256 (HMAC SHA-256)

• Required claims in the payload:

  • sub (subject – unique user ID)

  • iss (issuer)

  • iat (issued at)

  • exp (expiration time)

If using RS256, your token must also include a kid (Key ID) header referencing a key from your JWKS endpoint.

---

Enabling user auth

To configure user authentication, login to the Loyalty Console and navigate to the Settings > Tenant screen. From here, you can specify:

• Algorithm: HS256 or RS256

• Issuer: The expected value of the iss claim

• Shared Key: The symmetric key for signing/validating tokens (if using HS256)

• JWKS URL: The URL for your JWKS (if using RS256)

Once configured, WLL will begin validating user access tokens from your system.

Specifying user auth config in the Loyalty Console

---

Authorization behaviour

• WLL uses your token for authentication only.

• Authorization is handled internally based on the authenticated user’s account.

• Claims in the JWT (e.g. roles, scopes) are not used for permissions.