Table of Contents

Restricting your HelpDocs with Custom JWT SSO

Our docs are a great thing for your site's SEO and your brand. But sometimes, for whatever reason, you may want to restrict your HelpDocs to just users of your app.

Taylor Sloane Updated by Taylor Sloane

Our docs are a great thing for your site's SEO and your brand. But sometimes, for whatever reason, you may want to restrict your HelpDocs to just users of your app.

Never fear. If you have a developer on your team, you can generate unique JSON Web Tokens (JWT) for each user on your server, then cookie them to your users' browsers. Only users you've issued a JWT will be able to view your docs, and only while that JWT is valid 💪

Use our JWT Studio to create and validate your JWTs 💫
Users you identify with JWT auth are excluded from your HelpDocs user limits, so you can happily use this for all your users

Creating the JWT

We only require your JWT to contain a few standard fields. Here's what we're expecting:

"exp": 1531713013,
"iat": 1531540153,
"aud": "" // or ["", ...]

We will reject your JWT if:

  • exp is in the past (i.e. the token has expired)
  • iat is in the future (i.e. the token has time traveled)
  • aud does not equal (if it's a string) or contain (if it's a string array) your HelpDocs subdomain in the format or your custom domain in the form Domains should not have a trailing slash.

You can manage token expiry yourself by setting exp to a certain number of minutes or days in the future.

Signing the JWT

  1. In your HelpDocs dashboard head to Settings > Users > Access
  2. Head to Single Sign On and find JWT
  3. Click ⋮ More > Connect
  4. Add the generated Secret Key to your application
We recommend using your Secret Key as an environment variable, not hardcoding in your application code. That way it'll stay secret, the way it was intended.
NEVER use your secret key in client-side code. Anyone with this key can fool us into thinking they're acting on your behalf.

You can then sign your JWT with this key. We only support the HS256 signing algorithm.

If you lose control of your Secret Key, you can regenerate it at any time in the same place. You can also disable JWT auth completely.

Using the JWT to Identify a User to HelpDocs

Passing the JWT as a Query Parameter

You can send us the JWT on any page of your docs by hardcoding into the URL as the query parameter.

Be aware that this URL is easily shareable, and users could choose to share that link with people you didn't originally intend to access your docs.

It's also possible, and preferable, to cookie the JWT directly to a user's browser. There's a few ways to do this.

  • If you're using a custom domain on your docs, you can set a first-party cookie on with name hd_jwt. Use the JWT string as the value. Set the expiry to the same time as the JWT itself.
  • Send the user to, where token is your JWT and forward is the path you'd like us to send the user after dropping the cookie.
  • Include an iframe in your logged in app pages that has a src of

In options 2 and 3 we'll drop a cookie on that domain that expires at the same time as your JWT. They both work with your custom domain or HelpDocs subdomain.

Using the JWT as an API key

Certain routes in the API work with JWTs. These are:

  • GET /article
  • GET /article/:article_id
  • GET /category
  • GET /category/category_id

These keys will only allow the user to view articles they have access to. They're significantly more limited than regular API keys.

The JWT should be passed as a hd_jwt query parameter to one of the above routes.

Redirecting Logged Out Users

When a user hasn't visited your site for a while they won't have a cookie set. You'll want to override the default HelpDocs login page with a redirect to your own app. Something like this in Settings > Code > Javascript should work:

<script type="text/javascript">
(function() {
// Parse query string parameters
var qs = function (a) {
if (a === '') return {};
var b = {};
for (var i = 0; i < a.length; i += 1) {
var p = a[i].split('=', 2);
if (p.length === 1) {
b[p[0]] = '';
} else {
b[p[0]] = decodeURIComponent(p[1].replace(/\+/g, ' '));
return b;

if (window.location.pathname.indexOf('/login') === 0 && !qs.bypass) {
var redirectUri = ''; // Replace this with your login page URL
if (typeof qs.forward === 'string') redirectUri += '?hd_url=' + qs.forward;
return window.location.href = redirectUri;

If you're a stickler for user experience, your developers can set up a redirect back to the correct HelpDocs article after login by extracting the hd_url query param.

If as an administrator you wanna bypass this redirect you can still login at /login?bypass=1

Using JWT with Permission Groups

You can add permission groups to your JWTs to enable a user to see certain articles. The identifiers you'll need are available the same place you create and manage the group itself, in Settings > Users > Access.

To assign groups, just add a permission_groups property to your JWT. It should be an array of strings, each string representing a user group. Remember to include the group: prefix.

"exp": 1531713013,
"iat": 1531540153,
"aud": "" // or ["", ...]
"permission_groups": ["group:a9fk3uc7293"], // allocate one or more permission groups (remember the `group:` prefix)

Passing User Data in the JWT

If you want to be able to later identify a user in your template or some custom code, you can pass arbitrary parameters to us in the JWT. Just send a JSON-encoded string in the user_data field of the JWT. We'll make this data available to your templates as a readable cookie.

"exp": 1531713013,
"iat": 1531540153,
"aud": "" // or ["", ...]
"user_data": "{\"name\":\"Jake\"}", // optionally pass a JSON-encoded string of user data to decode on your docs later
There's an article about decoding that metadata here here

What did you think of this doc?

Using JWT Studio

Get in touch

This site is protected by hCaptcha and its Privacy Policy and Terms of Service apply.