Skip to content

Add documentation for Organizations integration with OAuth IdP#3364

Open
jfoshee wants to merge 6 commits into
mainfrom
cursor/oauth-orgs-integration-docs-76a1
Open

Add documentation for Organizations integration with OAuth IdP#3364
jfoshee wants to merge 6 commits into
mainfrom
cursor/oauth-orgs-integration-docs-76a1

Conversation

@jfoshee
Copy link
Copy Markdown
Contributor

@jfoshee jfoshee commented May 12, 2026

🔎 Previews:

What does this solve? What changed?

Adds documentation for the Organizations integration with OAuth Applications (OAuth IdP). When an instance has Organizations enabled, a new user:org:read scope becomes available for OAuth apps.

Changes made:

  1. how-clerk-implements-oauth.mdx:

    • Added user:org:read to the scopes table with a description of its availability and purpose.
    • Added a new "Organizations and OAuth" subsection under "Consent screen management" explaining:
      • The Organization selector shown on the OAuth consent screen when this scope is requested.
      • The org_id claim included in access tokens and ID tokens, and at info endpoints
    • Updated the authorization server metadata example to include user:org:read in scopes_supported and org_id in claims_supported.
  2. single-sign-on.mdx:

    • Added org_id, org_name, org_slug to the /oauth/userinfo response example and properties table.
    • Added org_id to the /oauth/token_info response example with a clarifying note.
    • Added org_id to the ID token additional claims table.
  3. Added a slug tooltip

Deadline

  • Backend PR to make this generally available is ready to go

Part of USER-5273

- Add user:org:read scope to the available scopes table
- Add Organizations and OAuth section explaining the Organization
  selector on the consent screen and org_id claim behavior
- Document org_id claim in ID token additional claims table
- Add org_id to userinfo and token_info response examples
- Add note about passing organization_id parameter to the
  authorization endpoint for customizing the consent flow
- Update authorization server metadata example to include
  user:org:read scope and org_id claim

Co-authored-by: Jacob Foshee <jfoshee@users.noreply.github.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented May 12, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview May 14, 2026 4:51pm

Request Review

Co-authored-by: Jacob Foshee <jfoshee@users.noreply.github.com>
@jfoshee jfoshee requested review from jescalan and wobsoriano May 13, 2026 00:07
@jfoshee jfoshee marked this pull request as ready for review May 13, 2026 00:08
@jfoshee jfoshee requested a review from a team as a code owner May 13, 2026 00:08
Copy link
Copy Markdown
Member

@wobsoriano wobsoriano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good on my end!

@jfoshee jfoshee force-pushed the cursor/oauth-orgs-integration-docs-76a1 branch from 19f05e9 to 6187acf Compare May 14, 2026 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants