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 💪
Creating the JWT
Your JWT needs exp and aud. iat is optional: we don't check it, but it's good practice to include it. Here's what we're expecting:
{
"exp": 1531713013,
"iat": 1531540153,
"aud": "https://your-domain.helpdocs.io" // or ["https://your-domain.helpdocs.io", ...]
}We will reject your JWT if:
- It isn't signed with HS256 using your Secret Key
- exp is missing or in the past (i.e. the token has expired)
- nbf, if you include it, is in the future (i.e. the token isn't valid yet)
- aud is missing or does not equal (if it's a string) or contain (if it's a string array) your HelpDocs subdomain in the format https://your-domain.helpdocs.io or your custom domain in the form https://your.domain.com. Domains should not have a trailing slash or a subdirectory.
You can manage token expiry yourself by setting exp to a certain number of minutes or days in the future.
Signing the JWT
- In your HelpDocs dashboard head to Settings > Sign-in & access
- Head to Single sign-on and find JWT
- Click the ⋯ menu > Enable
- Add the generated Secret Key to your application. You can get back to it any time from the ⋯ menu > View secret key
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: click the ⋯ menu > View secret key > Regenerate Secret Key. JWTs signed with the old key stop working, so you'll need to issue new ones. You can also disable JWT auth completely with Revoke secret key in the same menu.
Restricting Who Can Read Your Docs
Issuing JWTs doesn't restrict anything on its own. To keep your docs from anyone without a valid JWT:
- Head to Settings > Sign-in & access
- Under Who can read your help center, choose Only people who sign in
- Save your changes
Your team can still sign in with their HelpDocs accounts. If you leave this on Anyone, your docs stay public and a JWT only matters for articles restricted to permission groups.
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.
https://your-domain.helpdocs.io?hd_jwt=...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.
Dropping the JWT as a Cookie
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 .yourdomain.com 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 https://your-domain.helpdocs.io/login/jwt/token?hd_jwt=...&forward=..., where hd_jwt 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 https://your-domain.helpdocs.io/login/jwt/token?hd_jwt=...
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 with Lighthouse
Permissioned articles don't appear in Lighthouse by default. You can pass your JWT through to Lighthouse in the jwt parameter in the Lighthouse Widget API, and users will see any articles they have permission to view.
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
- GET /search
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.
You can use the Send the sign-in page somewhere else (if you restrict access to your docs entirely) or Signed-out readers on a restricted article (if only some of your docs require JWT auth) options in Settings > Sign-in & access to redirect logged out users to a page of your choice. We'll append ?forward= to the redirect, reflecting the user's intended page. Once you've cookied them with the JWT, you can redirect them back to the correct page.
/app or /login?hd_login=1Using 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: head to Settings > Groups and click Edit on a group to find its Group ID. A JWT with no permission groups can only read articles that aren't restricted to a group.
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": "https://your-domain.helpdocs.io", // or ["https://your-domain.helpdocs.io", ...]
"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. Any script on your docs can read that cookie, so don't put anything sensitive in it.
{
"exp": 1531713013,
"iat": 1531540153,
"aud": "https://your-domain.helpdocs.io", // or ["https://your-domain.helpdocs.io", ...]
"user_data": "{\"name\":\"Taylor\"}" // optionally pass a JSON-encoded string of user data to decode on your docs later
}