Want to control exactly which articles your external customers can see? JWT authentication combined with Permission Groups gives you powerful content restriction capabilities, all without requiring your users to create HelpDocs accounts π
By adding the right permission group information to your JWT tokens, you can seamlessly show different content to different user segments based on your own business logic.
Understanding JWT for Content Restriction
JSON Web Tokens (JWT) provide a secure way to authenticate external users and control their access to your Knowledge Base. When using JWT with HelpDocs, you can:
- Restrict entire Knowledge Base access to only authenticated users, by also choosing Only people who sign in under Who can read your help center in Settings > Sign-in & access
- Show specific articles to certain user segments
- Maintain content security without requiring users to create accounts
- Personalize the Knowledge Base experience based on customer attributes
Using JWT with Permission Groups
Permission Groups are the backbone of content restriction in HelpDocs. Each article can be assigned to specific groups, making it visible only to users who belong to those groups. A category can enforce its groups on everything inside it.
To assign Permission Groups to a JWT, you'll add a special property that tells HelpDocs which groups the user should have access to.
Adding Permission Groups to Your JWT
Simply add the permission_groups property to your JWT payload. This property should contain an array of strings, with each string representing a group identifier. Remember to include the group: prefix with each group ID.
{
"exp": 1631713013,
"iat": 1631540153,
"aud": "https://your-domain.helpdocs.io",
"permission_groups": ["group:a9fk3uc7293"]
}"permission_groups": ["group:a9fk3uc7293", "group:b8dk2lm5721"]Implementation Steps: Hosterful Example
Let's walk through a practical example of implementing content restriction for a service called Hosterful where you want to show special content only to verified hosts.
Step 1: Set Up Permission Group
- Head to Settings > Groups
- Click Create group and name it "All-Star Hosts"
- Note the Group ID (something like
a9fk3uc7293) at the top of the panel
Step 2: Assign Content to the Group
- Head to Content and find the "All Star Hosts" category
- Click the key icon on the category
- Under Groups, select the "All-Star Hosts" permission group you just created
- Check Enforce permissions on all descendant content
- Click Apply changes. Now everything in this category is restricted to only users with this permission
Step 3: Create JWT with Permission Group
There's two options:
- Use JWT Studio: in Settings > Groups, click Edit on your group, then click Generate a JWT for this group
- In your web application, generate a JWT token that includes the "All-Star Hosts" permission group:
{ "exp": 1648678400, // Token expiration (rotate monthly) "iat": 1646000000, // Token creation time "aud": "https://hosterful-support.helpdocs.io", "permission_groups": ["group:all_star__hosts_id"] }Replace "all_star__hosts_id" with the actual group ID you noted earlier.
Step 4: Create Access Link for Verified Hosts
- Create a link to your Knowledge Base that includes the token:
https://hosterful-support.helpdocs.io?hd_jwt=YOUR_GENERATED_TOKEN - Place this link in your host dashboard or include it in communications to verified hosts
- Set up a system to regenerate this token monthly for security
Finding Your Permission Group IDs
The group identifiers you need for the JWT are available in the same place you create and manage your Permission Groups.
- Head to Settings > Groups
- Click Edit on a group. Its alphanumeric Group ID is at the top of the panel
group: prefix. Omitting this prefix will cause the permission check to fail.Advanced Usage
Beyond basic permission group assignment, you can build more sophisticated access control:
- Combine permission groups with user data in the JWT
- Create time-limited access by setting appropriate JWT expiration
- Dynamically assign permission groups based on user attributes or subscription levels
Example: Hosterful Host Tiers
Note that user_data has to be a JSON-encoded string, not an object.
{
"exp": 1648678400,
"iat": 1646000000,
"aud": "https://hosterful-support.helpdocs.io",
"user_data": "{\"name\":\"Alex\",\"host_level\":\"Premium\"}",
"permission_groups": ["group:verified_hosts", "group:all_star_host_content"]
}Troubleshooting
If your verified hosts can't access content despite having JWT authentication:
- Verify the JWT token is valid using JWT Studio in your HelpDocs dashboard
- Check that permission group IDs include the
group:prefix - Ensure the articles are actually assigned to the permission groups in the JWT
- Confirm the JWT isn't expired (check the "exp" property)
- Check that the "aud" property is your HelpDocs subdomain or custom domain
- Testing while logged in to HelpDocs? We'll use your account's access rather than the JWT, so test in a private window
With JWT and Permission Groups working together, you can create a perfectly tailored documentation experience for your Hosterful verified hosts while maintaining full control over what they can access.