Restrict Content With Permissioning for External Users

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
• 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 or category can be assigned to specific groups, making them visible only to users who belong to those groups.

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"]
}

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

1. Head to Settings > Access > Groups
2. Create a new group called "All-Star Hosts"
3. Note the group ID (something like a9fk3uc7293) that appears next to your new group

Step 2: Assign Content to the Group

1. Navigate to the "All Star Hosts" category in your Knowledge Base
2. Edit the category settings
3. Select the "All-Star Hosts" permission group you just created
4. Save your changes—now this category is restricted to only users with this permission

Step 3: Create JWT with Permission Group

There's two options:

1. Use JWT Studio and generate a JWT for your Permission Group
2. 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

1. Create a link to your Knowledge Base that includes the token:
   https://demo.helpdocs.io?jwt=YOUR_GENERATED_TOKEN
2. Place this link in your host dashboard or include it in communications to verified hosts
3. 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.

1. Head to Settings > Access > Groups
2. The alphanumeric ID for each group will be visible next to the group name

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

{
  "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)

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.