API ReferenceProduct DocsLoyalty ConsoleSupport

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.

Last updated

Was this helpful?