Skip to content

fix: org_id claim docs #2676

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vinckr merged 1 commit into from
Jul 13, 2026
+27 −0
Merged

fix: org_id claim docs #2676

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/kratos/organizations/organizations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,18 @@ If the identity's `organization_id` points to an organization that was deleted,
scoped flow. This keeps account recovery and self-service settings working for users who were offboarded from a deleted
organization.

## Organization ID in OAuth2 and OpenID Connect tokens

When an organization member signs in through an Ory OAuth2 / OpenID Connect flow using the hosted consent screen (Account
Experience), the issued tokens carry the identity's organization ID:

- `organization_id` in the ID token claims.
- `organization_id` in the access token session data, surfaced under `ext` in JWT access tokens and promotable to a top-level
claim.

Identities that don't belong to an organization get no such claim. For configuration details and behavior, see
[Organization ID claim](../../oauth2-oidc/jwt-access-token.mdx#organization-id-claim).

## SAML

SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization data
Expand Down
15 changes: 15 additions & 0 deletions docs/oauth2-oidc/jwt-access-token.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,3 +239,18 @@ Without `preserve_ext_claims`, `another_claim` would not appear in the token.

This setting has no effect when `mirror_top_level_claims` is `true`, because mirroring already includes all custom claims in
`ext`.

## Organization ID claim

For Ory Network projects that use [organizations](../kratos/organizations/organizations.mdx) for B2B SSO, tokens issued through
Comment thread
vinckr marked this conversation as resolved.
the hosted consent screen (Account Experience) include the member's organization ID:

- **ID token:** `organization_id` is added to the ID token claims.
- **Access token:** `organization_id` is added to the session data. In JWT access tokens it appears under `ext`, and you can
promote it to a top-level claim by adding it to [`allowed_top_level_claims`](#add-custom-claims-to-top-level).

Identities that don't belong to an organization get no `organization_id` claim. The claim is omitted, not set to `null`.

Claims are snapshotted at consent time. Refresh token grants reuse the stored session, so a change to an identity's organization
takes effect on the next authorization flow. Projects with a custom consent UI control their own session claims and are
unaffected. Client credentials flows have no identity and never include the claim.
Loading