---
title: "JWT reader groups in your Document360 Knowledge base"
slug: "jwt-reader-groups"
description: "The JWT reader accounts can be associated with any existing reader groups on the Document360 project.The group restrictions can be applied to access specific content in the knowledge base."
tags: ["JWT"]
updated: 2026-08-19T04:27:41Z
published: 2026-08-19T04:27:41Z
canonical: "docs.document360.com/jwt-reader-groups"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.document360.com/docs/configuring-the-jwt-sso){target="_blank"}.
- At least one reader group must exist in your project. You can create and manage reader groups from **Settings** (<span class="fa-solid fa-gear"></span>) > **Users & permissions** > **Readers & groups** > **Reader groups** tab.
- You must have a **Project Owner** or **Admin** role to access reader group settings.

:::(Info) (<span class="fa-regular fa-circle-exclamation"></span> NOTE)
Reader group IDs are only available for JWT-configured projects. They are not visible on regular private knowledge base projects without JWT.
:::

---

## 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** (<span class="fa-solid fa-gear"></span>) > **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.

<div align="center">
<img src="https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/Screenshot-SSO_configuration_jwt_reader_group_id.png" class="article_image" alt="Reader groups interface showing Group ID below each group name with a copy icon.">
</div>

---

## 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:

```json
{
  "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:**

```json
"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.

:::(Info) (<span class="fa-regular fa-circle-exclamation"></span> NOTE)
Plan any reader group changes with this delay in mind, especially if you need access changes to take effect immediately for a specific reader.
:::

---

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

<div class="faq-wrapper" data-type="details-wrapper">
<details open>
<summary>
<p>Can a reader belong to more than one reader group?</p>
</summary>
<div data-type="details-content">
<p>Yes. You can include multiple Group IDs in the <code>readerGroupIds</code> array. The reader will inherit the combined access permissions of all assigned groups.</p>
</div>
</details>
<button class="details-arrow" type="button"></button>
</div>

<div class="faq-wrapper" data-type="details-wrapper">
<details>
<summary>
<p>Why can't I see the Group ID in my project?</p>
</summary>
<div data-type="details-content">
<p>Reader group IDs are only visible in JWT-configured projects. If your project does not have JWT SSO enabled, the Group ID field will not appear under the Reader groups tab.</p>
</div>
</details>
<button class="details-arrow" type="button"></button>
</div>

<div class="faq-wrapper" data-type="details-wrapper">
<details>
<summary>
<p>What happens if I add an invalid Group ID to the payload?</p>
</summary>
<div data-type="details-content">
<p>The token will still be generated, but the invalid Group ID will not map to any group. The reader may not have the expected access restrictions applied. Always verify Group IDs by copying them directly from the portal.</p>
</div>
</details>
<button class="details-arrow" type="button"></button>
</div>

<div class="faq-wrapper" data-type="details-wrapper">
<details>
<summary>
<p>If I remove a Group ID from the payload, does the reader lose access immediately?</p>
</summary>
<div data-type="details-content">
<p>No. Changes take effect only after the current token expires. If the token validity is set to 30 minutes, access changes will apply after 30 minutes from the last token issuance.</p>
</div>
</details>
<button class="details-arrow" type="button"></button>
</div>

<div class="faq-wrapper" data-type="details-wrapper">
<details>
<summary>
<p>Why is the Export CSV button disabled on my reader group page?</p>
</summary>
<div data-type="details-content">
<p>Document360 does not store reader details for readers authenticated through JWT, since they are authenticated externally in your own application. If a reader group consists entirely of JWT readers, the Export CSV button is disabled for all roles, including Admin and Owner, because there is no portal-stored reader data to export. If your project supports a mix of Normal, SSO, and JWT readers, Normal and SSO reader data can still be exported, but JWT reader data cannot. See the article on Export reader group for more detail on this limitation.</p>
</div>
</details>
<button class="details-arrow" type="button"></button>
</div>

## Related

- [Configure JWT for the knowledge base widget](/configuring-jwt-for-the-knowledge-base-widget.md)
- [JWT](/jwt.md)