> This page is for Docs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://zuora.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server.

# Use case example

> This example shows how Jane signs in to your site, receives a JWT in a login cookie, and accesses Zuora Experiences based on her mapped role.

This example shows how Jane signs in to your site, receives a JWT in a login cookie, and accesses Zuora Experiences based on her mapped role.

## Step 1 — Jane opens your login form

This example follows Jane from signing in to accessing a Zuora Experience.

Assume that:

* Your domain is `acme.com`.
* The cookie name configured in Zuora is `idp_session`.
* Your login system has been configured to issue a compatible JWT and publish its public key through a JWKS URL.

Jane visits `https://app.acme.com/login`.

This is your page and can use your own design. Jane enters her email address and password, then selects **Sign in**.

Step 2 — Your login form calls your authentication service

The login form sends Jane's credentials to your authentication service. The exact request format depends on your authentication system. For example:

```
POST https://login.acme.com/api/login
Content-Type: application/json

{
  "email": "jane@acme.com",
  "password": "<Jane's password>"
}
```

Your authentication service validates the credentials. The service, rather than the browser, determines the claims to include in the JWT.

Step 3 — Your authentication service creates or obtains the JWT

After validating Jane's credentials, your authentication service creates a signed JWT or obtains a compatible JWT from your identity provider.

The JWT can contain claims such as:

```json
{
  "sub": "jane@acme.com",
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "roles": ["billing-admin"]
}
```

The preceding example shows the claims in the JWT. It does not represent the login request.

In Case 1, your login system signs the JWT with your private key. In Case 2, your identity provider can provide the JWT, provided that it meets the requirements described in this guide, including the required `sub` claim, compatible signing, expiration, and any required role claims.

Step 4 — Your authentication service sets the cookie

After creating or obtaining the JWT, your authentication service returns it to the browser in the agreed cookie format:

```
HTTP/1.1 200 OK
Set-Cookie: idp_session=eyJhbGciOiJSUzI1Ni...; Path=/; HttpOnly; SameSite=None; Domain=.acme.com; Secure; Max-Age=7200
Content-Type: application/json

{ "ok": true }
```

Use the cookie-domain format required by your deployment so that the cookie is available to the relevant application and Experience subdomains.

The browser stores the `idp_session` cookie and sends it with subsequent requests to destinations covered by the cookie settings.

Step 5 — Your authentication service redirects Jane

After setting the cookie, your authentication service redirects Jane to the destination selected by your application. Both of the following destinations are supported:

**Option A — A full Experience page**

Jane is redirected to `https://experiences.acme.com/portal`. The page is a Zuora Experience. When it loads, Zuora reads the `idp_session` cookie, verifies the JWT, maps Jane's `billing-admin` role to the configured Zuora role, and loads the Experience.

**Option B — Your page with embedded Experience components**

Jane is redirected to `https://app.acme.com/dashboard`. This is your page and layout. It includes one or more Zuora Experience components. The components read the same `idp_session` cookie and verify the JWT using the same process.

The login flow is the same for both destinations. You do not need a separate authentication flow for a full Experience page and a page that embeds Experience components.

Step 6 — Zuora verifies the JWT

When the Experience loads, Zuora performs the following steps automatically:

1. Reads the configured login cookie.
2. Retrieves the public key that matches the JWT's `kid` value from the configured JWKS URL, or uses a cached copy of that key.
3. Verifies the JWT signature and confirms that the token has not expired.
4. Reads the `sub` claim and any available profile claims.
5. Reads the roles from the configured role claim path and applies the configured role mappings.

If these checks succeed, Jane can access the Experience according to her mapped role.

When the JWT expires, your authentication system must provide a valid replacement token or require Jane to sign in again, according to your implementation.