JWT reader groups

JWT reader groups let you control which sections of your private knowledge base each authenticated reader can access. When a reader logs in through JWT SSO, Document360 uses the reader group IDs in their token payload to determine which project versions, languages, categories, and articles they are allowed to view.

A JWT reader group is identical to a regular Document360 reader group. It inherits the same restriction settings. The only difference is how assignment works: instead of manually assigning readers in the portal, you pass their group IDs directly in the JWT payload.

When to use JWT reader groups

Use JWT reader groups when you need to enforce content-based access restrictions for readers who authenticate through JWT SSO.

Example scenario:
You sell an enterprise-tier add-on with its own configuration and API docs. Only customers who've purchased that add-on should see those articles — everyone else should just see the standard documentation.

Solution:

1. Create a reader group in the Document360 private project, granting access only to the enterprise add-on category.
2. Assign readers to this group based on their subscription tier (passed via JWT claims at SSO login).

Other common scenarios include:

• A partner integration guide visible only to readers from partner organizations, not general customers.
• Beta feature documentation restricted to customers enrolled in the beta program.
• Multiple customer segments (e.g., different regional product SKUs) who need different views of the same private knowledge base.

If your knowledge base is public or all authenticated readers should see the same content, reader group assignment is not required.

Before you begin

• Your project must have JWT SSO configured. If you have not set it up yet, see Configure JWT in Document360.
• At least one reader group must exist in your project. You can create and manage reader groups from Settings () > Users & permissions > Readers & groups > Reader groups tab.
• You must have a Project Owner or Admin role to access reader group settings.

Step 1: Get your reader group ID

Each reader group in Document360 has a unique ID that you include in the JWT payload to assign readers to that group.

1. Go to Settings () > Users & permissions > Readers & groups.
2. Select the Reader groups tab.
3. Locate the reader group you want to use. The Group ID is displayed below the group name.
4. Click the Copy icon to copy the Group ID to your clipboard.

Step 2: Add reader group IDs to your JWT payload

Once you have the Group ID, include it in the readerGroupIds field of your JWT payload.

Use the following JSON format:

{
  "username": "firstname + lastname",
  "firstName": "firstname",
  "lastName": "lastname",
  "emailId": "user emailId",
  "readerGroupIds": [
    "26b3812e-7879-4407-b1c9-5755c32b886a",
    "674eadcd-793f-4131-b1e0-c1f055cc83b7"
  ],
  "tokenValidity": 15
}

To assign a reader to multiple groups, add each Group ID as a separate entry in the array, separated by commas.

Example for multiple groups:

"readerGroupIds": ["26b3812e-7879-4407-b1c9-5755c32b886a", "674eadcd-793f-4131-b1e0-c1f055cc83b7"]

The tokenValidity field sets how long the token remains valid, in minutes. The minimum value is 5 minutes and the maximum is 1440 minutes (1 day).

When the reader authenticates and accesses the knowledge base, the restrictions defined in their assigned reader group apply automatically. They can only view the project versions, languages, categories, and articles permitted by that group.

When reader group changes take effect

Changes to reader group IDs in the payload (additions or removals) take effect only after the reader's current session expires, based on the token validity period.

Example: If the token validity is set to 30 minutes and you add a new Group ID to the payload, the change will not apply until 30 minutes have elapsed. The same applies when removing a Group ID.

Allowing readers to access content in multiple languages

When JWT authentication is configured for the widget, content visibility is determined by the permissions assigned to the authenticated reader and the content access filters configured within the widget. During login, the system validates the reader's permissions against the widget's content access settings. Only the permissions that overlap between the reader group and the widget configuration are considered when determining which content the reader can access.

If a reader belongs to a reader group that has language-level permissions, the widget will display content only in the languages available through that reader group, even if the widget itself is configured with broader access, such as project-level access.

To allow readers to access content in multiple languages

Ensure that the required languages are included in the reader group's permissions.
Verify that the widget's content access settings do not restrict access to a narrower set of content.

Configure the reader group with all languages that should be available to the reader upon login.

Best practices

• Keep token validity as short as is practical for your use case. Shorter validity means access changes take effect sooner.
• Audit your reader group assignments regularly to ensure readers are not retaining access to content they no longer need.
• Use the copy icon in the portal to paste Group IDs directly, avoiding manual transcription errors.
• Test reader group assignment after any payload change by logging in as a test reader account to confirm access restrictions are applied as expected.

FAQ