# Organizations in tokens (client guide)

This page is for developers of an application that signs users in with HelixIAM and serves several customer [organizations](../manage/organizations.md): how to learn which organization a user is working in, how to read all of their organizations, and how to switch silently.

## The active organization

A sign-in settles on one **active organization**, in this order:

1. the `organization` parameter on the authorization request (the organization's id or name);
2. the user's email domain, when it is a verified domain of an organization (an identifier-first step on the sign-in page);
3. the organization picker, when the user is a member of more than one organization.

If the user has one membership, that organization is active. If there is none, there is no active organization and no `organization` claim. The issuer never changes: it is the realm's, whatever the organization.

The active organization is kept for the session and on the authorization, so a refresh token keeps it. Membership is checked again on every token: a user who is no longer a member of the active organization gets tokens without the claim, not an error.

## Claims

### `organization`: the active organization

Always present while there is an active organization (ID token, access token and userinfo), without any extra scope:

```json
{
  "iss": "https://id.example.com/realms/acme",
  "sub": "…",
  "organization": {
    "id": "7c0d0d0e-…",
    "name": "northwind-traders",
    "roles": ["Org admin", "HR"]
  }
}
```

`roles` are the organization roles the user holds there: direct grants plus the roles inherited through the units they belong to. A member without roles has `"roles": []`.

### `organizations`: every membership (scope `organizations`)

The array of all of the user's organizations, in the same shape, is released **only when the scope `organizations` is granted**:

```json
{
  "organizations": [
    { "id": "7c0d0d0e-…", "name": "northwind-traders",  "roles": ["Org admin", "HR"] },
    { "id": "b2e41a90-…", "name": "fabrikam-ltd", "roles": [] }
  ]
}
```

Every realm has a client scope named `organizations`. To receive the claim, the client must be allowed that scope (Client → Scopes) and request it. Both claim names are reserved: a claim mapping cannot overwrite them. Neither claim is issued on `client_credentials` tokens or in impersonation sessions.

!!! warning "The `organizations` claim needs the scope"
    A token carries `organizations` only when the scope `organizations` is granted. Upgrading from an installation where every token carried it: see the [breaking changes](../operations/upgrades.md#organizations-v2).

## Example: sign in to a given organization

```
GET https://id.example.com/realms/acme/oauth2/authorize
  ?response_type=code
  &client_id=crm-web
  &redirect_uri=https%3A%2F%2Fcrm.example.com%2Fcallback
  &scope=openid%20profile%20email%20organizations
  &organization=northwind-traders
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
```

The user signs in (or is already signed in). `organization=northwind-traders` makes that organization active and shows its branding. If the user is not a member of it:

- when the organization has `requireMembership` on, the request returns to your `redirect_uri` with `error=access_denied` (and your `state`);
- otherwise the organization is not made active (the sign-in falls back to the normal rules).

`requireMembership` also applies when the organization was determined by the user's email domain or the picker, so leaving the parameter out does not skip it.

After the code exchange at `/realms/acme/oauth2/token`, the ID token and access token carry `organization` (and `organizations`, since the scope was requested).

## Switching the active organization silently

To move the user to another of their organizations without showing a page, repeat the authorization request with the other organization and `prompt=none`:

```
GET https://id.example.com/realms/acme/oauth2/authorize
  ?response_type=code
  &client_id=crm-web
  &redirect_uri=https%3A%2F%2Fcrm.example.com%2Fcallback
  &scope=openid%20profile%20email
  &organization=fabrikam-ltd
  &prompt=none
  &state=k3Jd82
  &nonce=Zq91xA
  &code_challenge=…
  &code_challenge_method=S256
```

The active organization belongs to the SSO session, so a switch made by one client changes the organization of the session's other clients on their next token. Best done in a hidden iframe or a redirect your application handles. The result arrives at your `redirect_uri`:

| Outcome | Response |
| --- | --- |
| The user is a member of `fabrikam-ltd` and its policy is met | A new `code`; the tokens it yields carry `organization` for `fabrikam-ltd`. The SSO session stays. |
| The user is not a member of `fabrikam-ltd` | `error=access_denied` |
| The organization's policy needs more from the user (for example MFA they have not completed in this session) | `error=interaction_required`; repeat the request without `prompt=none` so the user can complete it |
| The user has no SSO session, or the organization's maximum session time is exceeded | `error=login_required` |

Handle `interaction_required` and `login_required` by sending the user through a normal (interactive) authorization request with the same `organization` parameter.

!!! note "Pushed and signed authorization requests"
    With a pushed authorization request (PAR, `request_uri`), put `organization` and `prompt` in the pushed request: they are read from it, and the answer goes to its pushed `redirect_uri` with its pushed `state`. With a signed request object (`request`), put them in the request object. An unsigned `organization` or `prompt` added to the query string of such a request is ignored.

## Using the claims safely

- Authorize inside your application by `organization.id` and `organization.roles` of the **access token** the user is currently using, not by a client-side choice.
- Treat `organization.name` as a label that can change; key your data on `organization.id`.
- A user with no `organization` claim has no active organization: show your picker, or send them through an authorization request with `organization=`.

## See also

- [Organizations (B2B)](../manage/organizations.md)
- [OIDC flows & claims](oidc-flows.md)
- [Client scopes & claims](../manage/scopes-and-claims.md)
