From 511d792ee7b16778d38dfe322a7ff0945020d202 Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 13 Jul 2026 12:05:59 +0200 Subject: [PATCH] fix: org_id claim docs --- docs/kratos/organizations/organizations.mdx | 12 ++++++++++++ docs/oauth2-oidc/jwt-access-token.mdx | 15 +++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index ffeb5cca99..2671094a78 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -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 diff --git a/docs/oauth2-oidc/jwt-access-token.mdx b/docs/oauth2-oidc/jwt-access-token.mdx index ab05374505..87130ced04 100644 --- a/docs/oauth2-oidc/jwt-access-token.mdx +++ b/docs/oauth2-oidc/jwt-access-token.mdx @@ -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 +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.