JWT reader groups

Use JWT reader groups to control which parts of your private knowledge base each reader sees when they sign in through JWT. You add reader group IDs to the JWT payload, and each reader can then view only the project versions, languages, categories and articles their groups allow.

A JWT reader group is a regular Document360 reader group with the same restriction settings. The only difference is how readers are assigned: instead of adding readers to the group in the portal, you pass their group IDs in the JWT payload.

When to use JWT reader groups

Use JWT reader groups when readers sign in through JWT and different readers must see different content.

Example: You sell a paid add-on with its own configuration and API docs. Only customers who bought the add-on should see those articles; everyone else sees the standard documentation. To set this up:

1. Create a reader group in your private project that has access only to the add-on category.
2. In your application, add that group's ID to the JWT payload for readers who have the add-on.

Other common scenarios:

• A partner integration guide that only readers from partner organizations can see.
• Beta feature documentation for customers enrolled in the beta program.
• Several customer segments, such as different regional product versions, that need different views of the same private knowledge base.

If your knowledge base is public, or all signed-in readers should see the same content, you don't need reader groups.

Before you begin

• You need the Owner or Admin project role to access reader group settings.
• Your project must have JWT configured. If you haven't set it up yet, see Configure JWT in Document360.
• At least one reader group must exist in your project. To create one, see Create reader group.

How to assign JWT readers to reader groups

Step 1: Get your reader group ID

Each reader group has a unique ID that you add to the JWT payload.

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 appears 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

Add the Group ID to the readerGroupIds field of your JWT payload, in this format:

{
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "emailId": "john.doe@example.com",
  "readerGroupIds": [
    "26b3812e-7879-4407-b1c9-5755c32b886a",
    "674eadcd-793f-4131-b1e0-c1f055cc83b7"
  ],
  "tokenValidity": 15,
  "providerName": "app.example.com"
}

To assign a reader to more than one group, add each Group ID as a separate entry in the array, separated by commas:

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

The other fields in the sample work as follows:

When the reader signs in, the restrictions of their reader groups apply automatically. The reader sees only the project versions, languages, categories and articles those groups allow.

Step 3: Check that it works

1. Sign in to the knowledge base site as a test reader whose payload includes the Group ID.
2. Confirm that the reader sees the content the group allows and doesn't see restricted categories or articles.

When reader group changes take effect

When you add or remove a Group ID in the payload, the change applies only after the reader's current token expires, based on the tokenValidity value.

Example: If tokenValidity is 30 minutes and you add a Group ID to the payload, the reader gets the new access only after those 30 minutes have passed. The same applies when you remove a Group ID.

Use JWT reader groups with the knowledge base widget

If you also use JWT with the knowledge base widget, the widget shows a reader only the content allowed by both their reader groups and the widget's content access settings. This includes which languages the reader can see. For details, see Configure JWT for the knowledge base widget.

Limits and limitations

• JWT readers aren't stored in Document360 because they authenticate in your application. They don't appear in the portal and can't be added to groups through the portal.
• If a reader group contains only JWT readers, the Export CSV button is disabled for all roles, including Admin and Owner. In groups that mix Normal, SSO and JWT readers, you can export Normal and SSO reader data but not JWT reader data. See Export reader group.

Best practices

• Keep token validity as short as is practical. Shorter validity means access changes take effect sooner.
• Review reader group assignments regularly so readers don't keep access to content they no longer need.
• Copy Group IDs with the Copy icon in the portal instead of typing them, to avoid errors.
• After any payload change, sign in as a test reader to confirm the access restrictions apply as expected.

Related articles

• JWT
• Test your JWT configuration
• Manage reader content access

FAQ