Control Access to a Docs Site With Restricted Docs

NEW There are many reasons you might want to have a Docs site that isn't open to the public, but is viewable by the people you choose to let in. The new restricted Docs feature introduces the option to control access to a Docs site with your own visitor authentication. 

Restricted Docs is available to current Plus and Pro plans. 

Enabling, disabling, and configuring restricted Docs requires custom code development by your own team, working with the Docs API. 

How It Works

The details on how this works can get pretty deep into technical territory, but we'll start with a high level description:

When a visitor tries to access any part of a Docs site that is set to restricted, Help Scout will check to see if they've been authorized already, and if not, will send the request to your server to find out if they're allowed to view that site. Your server will authenticate the visitor and set a token in their web browser that will tell us to let them visit the site. 

Your server has the ultimate control of things and your developer team will get to define how visitors are authenticated and how long that authentication lasts. 

If a visitor is not able to authenticate with you, they'll see an error page your team defines instead of the restricted Docs site. 

It's a party! 

If that explanation still feels a little more technical than you want, let's go with an analogy to explain the idea. Think of the Docs site as a private party that you're hosting at Help Scout's house. 

When someone knocks at the door, Help Scout answers the door and looks to see if they have an active wristband that tells us they're allowed in. If they have a valid wristband, Help Scout lets them in to mingle. 

If they don't have that wristband, or the one they're wearing is expired, Help Scout calls you over to ask if they're allowed in. If you approve them, you'll give them a new wristband to wear so they can come and go during the time they're allowed in the party. 

You're in control of who gets the wristband, and how long that wristband is active. Help Scout will only let people with the wristband into the party. You'll be able to tell anyone without a wristband that they're not allowed into the party. 

Configure & Enable Restricted Docs

There is custom development work that your team will need to complete to get started. Point your coding team to the developer documentation here: Restricted Docs

Your developers will create an authentication endpoint on your side of things that will handle authenticating visitors and setting tokens to allow access.

When that is ready, they will make a call to the Docs API to enable restrictions for the site and set the location of your authorization endpoint using the Update Site Restrictions endpoint. 

Disable Restricted Docs

Disabling restricted Docs requires a call to the Docs API Update Site Restrictions endpoint. If you're unsure how to make calls to the API, you'll want to reach out to the team that set it up for you to get help with disabling it.