Shared Password Protection

Whether you're using your HelpDocs internally to train staff, or just because they're not ready for the limelight yet, there's a load of reasons you might want to password protect your HelpDocs.

Shared Password

HelpDocs makes it super simple to add a shared password that visitors will need to enter before they get to your docs.

Log in to HelpDocs at <your-subdomain>.helpdocs.io/app

  1. Go to SettingsAccess Control
  2. Toggle Enabled Shared Password on
  3. Under Shared Password enter a password of your choice
  4. Hit Save
You'll need to share this password with your team, so be sure not to use anything sensitive to you

Now when people visit your site they'll need to enter a password before they can read any docs.

Using Team Passwords for Single Sign On

You can also send the team password through as an hd_team query parameter. e.g. your-domain.helpdocs.io/?hd_team=password to automatically log in users

If you're looking to set up docs that only users logged into your app can view, the team password works great. 

Just load HelpDocs in an iframe on your dashboard when people log in, including the team password in the query string. We have a special URL for you to use, where you can set a duration for users to stay logged in.

The basic URL structure is https://<your-helpdocs>.helpdocs.io/_hd/team_sso?hd_team=<your-team-password>

Here's a snippet to get you started:

<iframe src="https://<your-helpdocs>.helpdocs.io/_hd/team_sso?hd_team=<your-team-password>" width="0" height="0" style="display: none"></iframe>

There's also a few parameters you can customize:

Query Parameter

Description

Default Value

hd_team
Required

Your shared team password

undefined

duration
Optional

How long (in days) you'd like users with this cookie to be logged in for, without requiring a password.

30

response_text
Optional

The text you'd like included in the response from this route. You usually won't need to set this.

🍪

redirect_uri
Optional

Where to redirect the user to after dropping a cookie. If you're using this route in an iframe, there's usually no need to set this.

undefined

You can log a user out of HelpDocs by passing an empty string as the password, or setting the cookie duration to a negative value
If you use a custom domain, be sure to swap that in for your HelpDocs subdomain in the above URLs

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 team password login page with a redirect to your own app. Something like this in Settings > Code > Custom Scripts should work:

<script type="text/javascript">
(function() {
if (window.location.pathname.indexOf('/team-login') === 0) {

// 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;
}(window.location.search.substr(1).split('&'));
var redirectUri = 'https://your-app.your-domain.com'; // Replace this with your login page URL
if (typeof qs.forward === 'string') redirectUri += '?hd_url=' + qs.forward;
return window.location.href = redirectUri;
}
})();
</script>

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.

Passing User Data to Your Template

If you want to identify a user later in your docs, you can pass us some data about them in the query parameter of the URL. This works if you're using the URL in an iframe or as a redirect.

The data should be JSON-encoded and sent as a hd_user_data query parameter. e.g.

https://helpdocs.your-custom-domain.com/_hd/team_sso?hd_team=password-here&hd_user_data={"name":"Jake","user_id":"1"}
Wanna access that data? Here's a guide.

What did you think of this doc?