Scopes & Claims Reference

Scopes overview

Trousseau implements a three-tier scope model. Each tier builds on the previous one.

Tier	Scope(s)	Description
1	`openid email profile`	Standard OIDC identity. Available to all partners.
2	`trousseau:context`	Ecosystem identifiers. Opt-in per partner.
3	`trousseau:organization`	Organization memberships. Opt-in for B2B partners.

Tier 1 — Standard OIDC

These scopes follow the OpenID Connect Core specification. They work with any OIDC client library without customization.

`openid` (required)

Always required. Tells Trousseau to return an ID token.

Claim	Type	Description
`sub`	`string` (UUID)	Unique user identifier in Trousseau. Stable across sessions.
`iss`	`string` (URL)	Issuer URL — your application's OIDC issuer.
`aud`	`string`	Your client ID.
`exp`	`number`	Token expiration (Unix timestamp).
`iat`	`number`	Token issuance time (Unix timestamp).

`email`

Claim	Type	Description
`email`	`string`	User's primary email address.
`email_verified`	`boolean`	Always `true`. Trousseau verifies all email addresses.

`profile`

Claim	Type	Description
`name`	`string`	Full display name (e.g., `"Jean Dupont"`).
`given_name`	`string`	First name (e.g., `"Jean"`).
`family_name`	`string`	Last name (e.g., `"Dupont"`).
`picture`	`string` (URL)	Avatar URL. Empty string if not set.

Example ID token (Tier 1)

{
  "iss": "https://auth.keysuite.app/application/o/your-slug/",
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "aud": "your-slug-oidc",
  "exp": 1712400000,
  "iat": 1712399700,
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://auth.keysuite.app/media/avatars/jean-dupont.jpg"
}

Tier 2 — Trousseau Context

Request the trousseau:context scope to receive ecosystem-level identifiers. This is useful when your application needs to correlate users across multiple Trousseau-connected apps.

Claim	Type	Description
`trousseau_user_id`	`string` (UUIDv7)	Stable ecosystem-wide user identifier. Shared across all Trousseau-connected applications. Unlike `sub` (which is the Authentik-internal UUID), this ID is portable and survives IdP migrations.
`locale`	`string` (BCP-47)	User's preferred locale (e.g., `"fr-FR"`, `"en-GB"`).

When to use Tier 2

You need to match users across multiple Trousseau-connected applications
You want to pre-set the UI language based on the user's preference
You need a stable user ID that won't change if the IdP backend is migrated

Example ID token (Tier 1 + 2)

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://auth.keysuite.app/media/avatars/jean-dupont.jpg",
  "trousseau_user_id": "018cc251-f400-78cc-8e0c-000fe440ee40",
  "locale": "fr-FR"
}

Request the trousseau:organization scope to receive the user's organization memberships in the KeySuite ecosystem. This is designed for B2B partners (PMS, hotel management tools) that need to know which organization(s) the user works for.

Claim	Type	Description
`organizations`	`array` of objects	All organizations the user is a member of.

Organization object

Field	Type	Description
`id`	`string` (UUIDv7)	Organization ID in KeySuite.
`name`	`string`	Organization display name.
`slug`	`string`	URL-safe identifier.
`role`	`string`	User's role in this organization: `admin`, `hr`, `accounting`, or `member`.

When to use Tier 3

Your application serves a specific organization (hotel, company)
You need to scope user actions to an organization context
You want to display organization-specific content or permissions

Handling multiple organizations

A user can belong to multiple organizations. If your application is organization-specific:

Check if the user belongs to your target organization by matching organizations[].id or organizations[].slug
If the user belongs to multiple organizations, present an organization selector
Store the selected organization in your application session

Example ID token (Tier 1 + 2 + 3)

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://auth.keysuite.app/media/avatars/jean-dupont.jpg",
  "trousseau_user_id": "018cc251-f400-78cc-8e0c-000fe440ee40",
  "locale": "fr-FR",
  "organizations": [
    {
      "id": "018cc251-f400-78cc-8e0c-000fe440ee40",
      "name": "Hotel Le Grand Paris",
      "slug": "hotel-le-grand-paris",
      "role": "admin"
    },
    {
      "id": "018dd362-a511-89dd-9f1d-111ff551ff51",
      "name": "Hotel Riviera Nice",
      "slug": "hotel-riviera-nice",
      "role": "member"
    }
  ]
}

Claims availability

Summary of where each claim is available:

Claim	ID Token	UserInfo	Access Token
`sub`	Yes	Yes	No
`email`	Yes	Yes	No
`email_verified`	Yes	Yes	No
`name`	Yes	Yes	No
`given_name`	Yes	Yes	No
`family_name`	Yes	Yes	No
`picture`	Yes	Yes	No
`trousseau_user_id`	Yes	Yes	No
`locale`	Yes	Yes	No
`organizations`	Yes	Yes	No

All claims are present in both the ID Token (JWT) and the UserInfo endpoint response. The access token is opaque and does not contain user claims.

Requesting scopes

Scopes are requested in the authorization request's scope parameter, space-separated:

# Tier 1 only
scope=openid email profile

# Tier 1 + 2
scope=openid email profile trousseau:context

# Tier 1 + 2 + 3
scope=openid email profile trousseau:context trousseau:organization

You can only request scopes that have been approved for your application during onboarding. Requesting unauthorized scopes will result in an invalid_scope error.