Document token revocation

[indeewari]

Purpose

Token revocation had no documentation beyond the endpoint's entry in the OpenAPI spec. Nothing described the token family, user-scoped revocation, where enforcement happens, or any of the settings that control it.

This adds a Token Revocation reference under the OAuth/OIDC protocol guides and fills the matching gaps in the configuration reference. Follows the feature work in #4300, #4591 and #4669.

Approach

New page — docs/content/guides/protocols/oauth-oidc/token-revocation.mdx, placed in Token Operations beside Token Introspection, matching the reference doc type its siblings use.

It is organised around the three scopes a reader has to distinguish, since they behave differently and are triggered differently:

Scope	What it invalidates
Single token	One token, by its jti
Grant	Every token of one authorization grant, by its tfid
User	Every token belonging to one user, by its sub

Then where revocation is enforced, and the settings that control all of it.

Configuration reference — three gaps closed in docs/content/deployment/configuration.mdx:

• Every revocation setting was undocumented. Added the four oauth.revocation.* / oauth.token_revocation.* keys, oauth.token_exchange.token_family, and the three server.security.token_revocation.* keys.
• userDeletionFlow was missing from the supported flow types, which listed only five.
• Added a note on the propagation delay for enforcement on protected API requests, next to the setting that controls it.

Two operational facts called out deliberately

Both are things an integrator otherwise discovers from a confusing bug report:

• oauth.token_revocation.enabled does more than gate the endpoint. Setting it to false also turns off the check that rejects revoked tokens during introspection, the refresh grant, and token exchange. The page and the config table both say so explicitly.
• DELETE /users/{id} does not revoke tokens. The deletion flow runs on Console deletion. Anyone scripting offboarding against the API needs to know the tokens stay valid, so this is a :::warning rather than a passing mention.

Verification

Every claim was checked against the implementation rather than against the design documents, including the two that turned out to be more subtle than the design notes suggested (what oauth.token_revocation.enabled gates, and that token_type_hint is accepted and then discarded).

./scripts/docs-lint.sh passes on both changed files, with no new sidebar orphans.

Related Issues

• N/A

Related PRs

• Add token family id (tfid) for grant-scoped revocation #4300 grant-scoped revocation through the token family
• Add criteria-based revocation administration flows #4591 criteria-based revocation machinery
• Run console user deletion through a configurable administration flow #4669 the default user deletion flow

Checklist

• Followed the contribution guidelines.
• Manual test round performed and verified.
• Documentation provided. (Add links if there are any)
  • Ran Vale and fixed all errors and warnings
• Tests provided. (Add links if there are any)
  • Unit Tests
  • Integration Tests
• Breaking changes. (Fill if applicable)
  • Breaking changes section filled.
  • breaking change label added.

Security checks

• Followed secure coding standards in WSO2 Secure Coding Guidelines
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a comprehensive Token Revocation guide covering individual tokens, grant families, and user-scoped revocation.
  • Documented RFC 7009 behavior, ownership validation, token propagation, replay and logout triggers, user deletion, enforcement, consistency, and failure scenarios.
  • Added configuration guidance for revocation behavior, protected APIs, synchronization, and administration.
  • Added Token Revocation to the OAuth/OIDC Token Operations navigation.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change documents OAuth token revocation configuration and behavior. It adds a complete token revocation guide and links the guide from the OAuth/OIDC Token Operations sidebar.

Changes

OAuth token revocation documentation

Layer / File(s)	Summary
Revocation configuration and lifecycle settings docs/content/deployment/configuration.mdx	Documents token revocation triggers, token-family inheritance, userDeletionFlow, and protected-API revocation consistency settings.
Revocation guide and navigation docs/content/guides/protocols/oauth-oidc/token-revocation.mdx, docs/sidebars.ts	Adds the token revocation reference guide and links it under OAuth/OIDC Token Operations.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• thunder-id/thunderid#3872: Implements refresh-token rotation revocation covered by this documentation.
• thunder-id/thunderid#4430: Covers revocation endpoint behavior and client authentication.

Suggested labels: skip-changelog

Suggested reviewers: thiva-k, thamindudilshan

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding documentation for token revocation.
Description check	✅ Passed	The description covers the purpose, approach, related work, verification, checklist, and security checks required by the template.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

docs/content/deployment/configuration.mdx

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

docs/content/guides/protocols/oauth-oidc/token-revocation.mdx

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

docs/sidebars.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/deployment/configuration.mdx`:
- Around line 1089-1091: Remove the unrelated system_permission_prefix :::tip
block from the token revocation documentation, or relocate it beside the
server.security.system_permission_prefix setting; keep the token revocation
content focused and otherwise unchanged.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 66e8e6b5-4153-4afc-8db3-0369d30be7c8

📥 Commits

Reviewing files that changed from the base of the PR and between 98ca9ef and dfef90a.

📒 Files selected for processing (3)

• docs/content/deployment/configuration.mdx
• docs/content/guides/protocols/oauth-oidc/token-revocation.mdx
• docs/sidebars.ts

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Remove the unrelated system_permission_prefix tip.

This PR documents token revocation. The tip does not describe token revocation. Delete it or move it next to the server.security.system_permission_prefix setting.

Proposed fix

-:::tip
-If you set a custom `system_permission_prefix`, update the Console scopes to match the new permission strings and restart the server.
-:::

As per coding guidelines, “Keep changes minimal and focused on the requested task.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	:::tip
	If you set a custom `system_permission_prefix`, update the Console scopes to match the new permission strings and restart the server.
	:::

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/content/deployment/configuration.mdx` around lines 1089 - 1091, Remove
the unrelated system_permission_prefix :::tip block from the token revocation
documentation, or relocate it beside the
server.security.system_permission_prefix setting; keep the token revocation
content focused and otherwise unchanged.

Source: Coding guidelines

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!