SDK Authentication

The WL App SDK authenticates the embedded Loyal Guru module by passing a Customer JWT during SDK initialization. The commercial SDK contract names this parameter jwt; current Web SDK examples may expose it as token. In both cases, the SDK sends the JWT to the embedded module internally; the host does not need to set cookies or inject authorization headers into the iframe.

IAM policy (recommended default)

Loyal Guru is not a general-purpose IAM. For SDK and host integrations:

1. Recommended default: the retailer authenticates the Customer (their login, SSO, or IAM). The host backend issues a short-lived Customer JWT and the SDK initializes with that token. Loyalty modules never replace the retailer's login product.
2. Exception: for very small Companies on the Full White Label App that have no identity stack, Loyal Guru may manage registration and login inside the app only (LG-managed authentication). That mode is scoped to the approved WL App channel — not an auth-only SDK for arbitrary retailer websites.
3. If the retailer needs a full identity platform for web or multi-channel login outside that exception, they should use their own IAM (or a dedicated IdP) and integrate Loyal Guru with retailer-issued JWT or federated identity.

Product framing: Customer authentication (IAM).

Authentication Models

Model	How it works	When to use
Retailer-issued JWT	The retailer backend signs a Customer JWT and passes it to EmbedLoyaltyApp.init(). Loyal Guru validates it.	Recommended default when the retailer owns Customer login (app, web, or IAM).
LG-managed authentication	Loyal Guru manages registration, login, and session inside the WL App experience.	Exception only for approved very small Full WL App clients with no retailer IAM. App channel only — not a standalone auth product.
Federated identity	The retailer SSO/OIDC/SAML layer is connected to Loyal Guru authentication.	Enterprise deployments with existing identity infrastructure.

Token Refresh Flow

Refresh Implementation

EmbedLoyaltyApp.onTokenRefreshRequested(async () => {
  const response = await fetch('/api/loyalty-token/refresh');
  const { token } = await response.json();
  EmbedLoyaltyApp.refreshToken(token);
});

Use short-lived tokens and always generate a fresh token during refresh. Do not call refreshToken() with an expired token.

Supported JWT Algorithms

The token passed to EmbedLoyaltyApp.init({ token }) can use HS256 or RS256, depending on the integration.

HS256

HS256 uses a shared secret provided through a secure channel.

{
  "alg": "HS256"
}

Example payload:

{
  "customer_id": "201",
  "company": "company-test",
  "expires_at": "2025-09-29T12:00:00Z"
}

Claim	Description
customer_id	Loyal Guru Customer identifier.
company	Company slug.
expires_at	Expiration date in UTC ISO8601 format.

HS256 is supported for existing integrations.

RS256

RS256 is recommended for new integrations when the retailer does not want to share a symmetric secret. The retailer signs tokens with a private key and shares only the public key with Loyal Guru.

{
  "alg": "RS256",
  "kid": "<uuid>"
}

Example payload:

{
  "resource": "Customer",
  "customer_id": 201,
  "company": "company-test",
  "exp": 1798761599
}

Claim	Description
resource	Fixed value: Customer.
customer_id or customer_code	Customer identifier. One is required.
company	Company slug.
exp	Standard Unix expiration timestamp in seconds.
kid	Key identifier used for key rotation.

Do not include unnecessary personally identifiable information in the JWT. Customer identity is resolved through customer_id or customer_code.

Customer JWT Callback

Some flows need the host to know which Customer was authenticated inside a Loyal Guru-managed login flow. In that case, the embedded module can send a Loyal Guru-signed JWT to the host through the SDK.

EmbedLoyaltyApp.onCustomerJwt(({ jwt, origin }) => {
  // Forward the JWT to your backend.
  // Verify it server-side before trusting the customer_id.
});

This is separate from the init token. The host backend must verify the received token before using the decoded Customer identity.

Security Checklist

Area	Requirement
Token generation	Generate tokens server-side only.
Token lifetime	Use short-lived tokens and implement refresh.
Secrets	Do not hardcode secrets or production JWTs in frontend code.
Origin validation	Restrict host and iframe origins in production.
PII	Keep JWT payloads minimal.
Key rotation	Use kid when using RS256.

note

Signed SSO Redirect is a different flow: the WL App hands a signed-in Customer off to another of your systems with a JWT that you validate. See Signed SSO Redirect.