fix: add multi-org session cookie behavior and permissions token (gap report) by tamalchowdhury · Pull Request #712 · kinde-oss/documentation

tamalchowdhury · 2026-04-13T07:10:42Z

Explains two areas of existing Kinde behavior that users are hitting unexpectedly, surfaced in the March 2026 gap report.

session-management.mdx — new section explaining that the refresh_token cookie is shared across all tabs; switching orgs in one tab affects others on their next refresh, with a workaround for app-layer isolation
navigate-between-organizations.mdx — short callout + cross-link to session management
Permissions in access tokens (Gap 8)

about-access-tokens.mdx — new ## Can I remove claims to reduce token size? section covering how to strip permissions, feature_flags, and other claims via the user token generation workflow
user-permissions.mdx — cross-link to access tokens and the workflow

Summary by CodeRabbit

Documentation
- Clarified organization-switching behavior: refresh token cookies are shared across tabs and can change other tabs’ org context on next token refresh.
- Expanded access token guidance: reorganized examples and added guidance on which claims are auto-populated and how to reduce token size.
- Added FAQs on permissions in access tokens and cross-tab org switching.

… (gap report) Made-with: Cursor

coderabbitai · 2026-04-13T07:10:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c8c504a1-a86e-44db-a34a-d8792f95e638

📥 Commits

Reviewing files that changed from the base of the PR and between 6ddd302 and 84bc0fd.

📒 Files selected for processing (1)

src/content/docs/build/tokens/about-access-tokens.mdx

Walkthrough

Updated documentation pages for authentication, session management, and access tokens: metadata dates advanced; new FAQs describe cross-tab refresh token behavior when switching organizations, how permissions appear in access tokens, and options to remove claims. No code or public API changes.

Changes

Cohort / File(s)	Summary
Organization Switching & Session Management `src/content/docs/authenticate/manage-authentication/navigate-between-organizations.mdx`, `src/content/docs/authenticate/manage-authentication/session-management.mdx`	Added FAQ text explaining that the domain-scoped `refresh_token` cookie is shared across browser tabs and is updated when calling `login({ orgCode })`, causing other tabs to adopt the new org on their next token refresh. Metadata `updated` dates bumped to 2026-04-13.
Access Tokens & Permissions `src/content/docs/build/tokens/about-access-tokens.mdx`, `src/content/docs/manage-users/roles-and-permissions/user-permissions.mdx`	Reorganized the access token page (moved example token earlier and switched to `jsonc`), removed duplicate example block, added guidance that Kinde auto-populates claims (`permissions`, `feature_flags`, `org_code`) and how to remove claims via the user token generation workflow or server-side calls. Added FAQ clarifying permissions in access tokens. Metadata `updated` dates updated to 2026-04-13.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through docs with nimble paws,
New FAQs fixed a few loose claws,
Tokens, tabs, and permissions clear—
A tidy trail for folks who're near.
Hooray for docs! 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main changes: adding documentation about multi-org session cookie behavior and permissions token handling based on a gap report.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch tamal/update/multi-org-sessions-and-permissions

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cloudflare-workers-and-pages · 2026-04-13T07:12:00Z

Deploying kinde-docs-preview with Cloudflare Pages

Latest commit:	`de9d468`
Status:	✅ Deploy successful!
Preview URL:	https://04737f3f.kinde-docs-preview.pages.dev
Branch Preview URL:	https://tamal-update-multi-org-sessi.kinde-docs-preview.pages.dev

View logs

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/content/docs/authenticate/manage-authentication/navigate-between-organizations.mdx (1)

120-124: Keep this as a brief callout and defer detailed behavior to the canonical page.

Lines 120-123 duplicate behavior details that already exist in src/content/docs/authenticate/manage-authentication/session-management.mdx (Lines 50-54). Trimming this section reduces drift risk.

Proposed simplification

 ## Does the refresh token cookie affect other browser tabs when switching orgs?
 
-Yes. The refresh token cookie is shared across all browser tabs on the same domain. When a user switches to a different organization, the shared cookie is updated with the new org's refresh token. Other open tabs will pick up the new organization context on their next token refresh.
+Yes. Because the refresh token cookie is shared across tabs on the same domain, switching orgs in one tab can affect others after their next refresh.
 
 For more on how this works and available workarounds, see [Session management](/authenticate/manage-authentication/session-management/#does-switching-organizations-affect-other-browser-tabs).

Based on learnings: In MDX documentation files, prefer “document once, reference anywhere” to avoid duplicated behavior descriptions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/content/docs/authenticate/manage-authentication/navigate-between-organizations.mdx`
around lines 120 - 124, Remove the duplicated explanatory paragraph under the
heading "Does the refresh token cookie affect other browser tabs when switching
orgs?" and replace it with a short one-line callout that points readers to the
canonical "Session management" page (the content in session-management.mdx) for
full behavior details; ensure the new callout briefly states that the refresh
token is shared across tabs and links to
/authenticate/manage-authentication/session-management/#does-switching-organizations-affect-other-browser-tabs
so the detailed behavior remains in one place.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/content/docs/build/tokens/about-access-tokens.mdx`:
- Around line 42-77: The JSON token example is malformed: close the unterminated
strings for the "aud" entry value, each entry in the "permissions" array (e.g.,
"view:profile"), and the "scp" array value ("offline"), ensure proper commas
between array items/fields, and remove the JavaScript comment after "sub"
(replace it with a string value only); update the "aud", "permissions", "scp",
and "sub" entries so the entire code block is valid JSON.

---

Nitpick comments:
In
`@src/content/docs/authenticate/manage-authentication/navigate-between-organizations.mdx`:
- Around line 120-124: Remove the duplicated explanatory paragraph under the
heading "Does the refresh token cookie affect other browser tabs when switching
orgs?" and replace it with a short one-line callout that points readers to the
canonical "Session management" page (the content in session-management.mdx) for
full behavior details; ensure the new callout briefly states that the refresh
token is shared across tabs and links to
/authenticate/manage-authentication/session-management/#does-switching-organizations-affect-other-browser-tabs
so the detailed behavior remains in one place.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6150f4c8-752d-4f21-80a3-edfbd740006c

📥 Commits

Reviewing files that changed from the base of the PR and between d03feb0 and 6ddd302.

📒 Files selected for processing (4)

src/content/docs/authenticate/manage-authentication/navigate-between-organizations.mdx
src/content/docs/authenticate/manage-authentication/session-management.mdx
src/content/docs/build/tokens/about-access-tokens.mdx
src/content/docs/manage-users/roles-and-permissions/user-permissions.mdx

alex72508

LGTM

fix: add multi-org session cookie behavior and permissions token docs…

6ddd302

… (gap report) Made-with: Cursor

tamalchowdhury requested a review from a team as a code owner April 13, 2026 07:10

coderabbitai bot reviewed Apr 13, 2026

View reviewed changes

Comment thread src/content/docs/build/tokens/about-access-tokens.mdx Outdated

tamalchowdhury changed the title ~~⚠️ fix: add multi-org session cookie behavior and permissions token (gap report)~~ fix: add multi-org session cookie behavior and permissions token (gap report) Apr 13, 2026

tamalchowdhury added 2 commits April 13, 2026 14:10

add jsonc lang type in example access token

11d846a

fix the broken json string values

84bc0fd

alex72508 approved these changes Apr 13, 2026

View reviewed changes

Merge branch 'main' into tamal/update/multi-org-sessions-and-permissions

de9d468

tamalchowdhury merged commit c1de5be into main Apr 14, 2026
6 checks passed

tamalchowdhury deleted the tamal/update/multi-org-sessions-and-permissions branch April 14, 2026 06:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: add multi-org session cookie behavior and permissions token (gap report)#712

fix: add multi-org session cookie behavior and permissions token (gap report)#712
tamalchowdhury merged 4 commits intomainfrom
tamal/update/multi-org-sessions-and-permissions

tamalchowdhury commented Apr 13, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Apr 13, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Apr 13, 2026 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

alex72508 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

tamalchowdhury commented Apr 13, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

cloudflare-workers-and-pages bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying kinde-docs-preview with Cloudflare Pages

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alex72508 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tamalchowdhury commented Apr 13, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Apr 13, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Apr 13, 2026 •

edited

Loading