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:
- Create a reader group in your private project that has access only to the add-on category.
- 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.
Group IDs appear on the Reader groups tab once JWT is configured for the knowledge base site or for the knowledge base widget.
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.
- Go to Settings () > Users & Permissions > Readers & groups.
- Select the Reader groups tab.
- Locate the reader group you want to use. The Group ID appears below the group name.
- 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": [
"<group-id-1>",
"<group-id-2>"
],
"tokenValidity": 15,
"providerName": "app.example.com"
}
If you leave readerGroupIds out, or send an empty array, the reader can see the whole project. To restrict a reader, always send at least one Group ID.
To assign a reader to more than one group, add each Group ID as a separate entry in the array, separated by commas:
"readerGroupIds": ["<group-id-1>", "<group-id-2>"]
The other fields in the sample work as follows:
| Field | What it does |
|---|---|
tokenValidity |
How long the reader's session lasts, in minutes, from 5 to 1,440 (24 hours). |
providerName |
Recommended when your project has 2 or more JWT configurations. Set it to the configuration's Domain name (Settings > Users & Permissions > Enterprise SSO > Edit icon > Server settings). It lets Document360 renew the session through the right Login URL. See Re-authenticating readers with multiple JWT configurations. |
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
- Sign in to the knowledge base site as a test reader whose payload includes the Group ID.
- Confirm that the reader sees the content the group allows and doesn't see restricted categories or articles.
When reader group changes take effect
Group IDs are read when the reader signs in, so a change applies the next time the reader signs in through your application. The session lasts tokenValidity minutes and is extended while the reader keeps browsing, so an active reader can keep their old access for longer.
To apply a change immediately, for example when you remove access, sign the reader out of the knowledge base by sending them to https://<your KB domain>/jwt/logout. Their next visit signs them in with the new Group IDs.
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.
Considerations
- 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.
- Because JWT readers are not stored as reader accounts in Document360, they do not count toward your project's reader account limit. This differs from Normal and SSO readers, which do occupy a reader account slot on your plan.
- 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 the session length (
tokenValidity) as short as is practical. To apply an access change at once, sign the reader out instead of waiting for the session to end. - 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.
FAQ
Can a reader belong to more than one reader group?
Yes. Add several Group IDs to the readerGroupIds array. The reader gets the combined access of all assigned groups.
Why can't I see the Group ID in my project?
Group IDs appear only once JWT is configured for the knowledge base site or for the knowledge base widget. If neither has JWT configured, the Group ID doesn't appear on the Reader groups tab.
What happens if I add an invalid Group ID to the payload?
The sign-in still completes, but Document360 ignores Group IDs that do not match an existing reader group. A common cause is a leading or trailing space in the UUID introduced during manual copying and pasting. Because Document360 performs a strict match, IDs with extra whitespace are silently discarded without returning an error.
If the readerGroupIds array contains only whitespace-padded or otherwise malformed IDs, Document360 treats it as if no Group IDs were provided and grants the reader access to the whole project.
If none of the IDs match, readers of a private knowledge base see "Sorry, you're not authorized to access this documentation." If the groups exist but provide no access to content, readers see "Sorry, you don't have permission to access this content, please contact your administrator."
Always use the Copy icon in the portal to copy Group IDs directly to your clipboard and avoid extra whitespace or formatting errors.
Why is the Export CSV button disabled on my reader group page?
Document360 doesn't store details of readers who authenticate through JWT, so a group made up only of JWT readers has no reader data to export. See Export reader group.
My reader is still seeing content from their previous reader group after I updated the JWT payload with a new reader group ID. What should I do?
Reader group IDs are applied when the reader signs in, not each time they load a page. An active Document360 session retains the previous group's access until the session expires or the reader is explicitly signed out.
To apply the new reader group immediately:
- Direct the reader to
https://<your KB domain>/jwt/logoutto end their current Document360 session. - Have your application issue a new JWT token with the updated
readerGroupIds. - Ask the reader to sign in again to apply the new group permissions.
If the new group still does not apply:
- Verify that the Group ID is correct and contains no extra characters or spaces. Use the portal's Copy icon to copy Group IDs.
- Check the reader group's content access under Settings > Users & Permissions > Readers & groups > Reader groups.
- After signing out, test in a fresh private browsing session to rule out cached state.
Incognito or private browsing alone does not clear an active server-side Document360 session. The /jwt/logout endpoint is required to clear the session and ensure the updated Group IDs are read at the next sign-in.