Visitor Authentication in GitBook is a powerful way to further control who has access to the information you're publishing. By setting up a custom login screen, you can customize the experience for private materials you might have on GitBook.
In order to use Visitor Authentication, you'll need to configure a few tools first—Including setting up a server to handle the sign-in flow your users will go through.
The rest of this guide follows this GitHub repository, and will explain the setup and code through the main functionalities of the demo app.
To get started, you'll need to clone the repository we're following in this guide. It requires a few pieces to be configured (which we'll cover in the following steps).
To clone, you can run the following command in your terminal:
git clone email@example.com:GitbookIO/va-nextjs-clerk.git
After cloning the repository, you can
cd into the root of the project, and install it's dependencies using
Publish GitBook Space with Visitor Authentication
In order to use a custom sign-in page for users, we'll need to publish a GitBook space with Visitor Authentication.
Keep in mind, this feature is only available for Pro and Enterprise plans.
In the space you would like to use, head to the Share Modal in the upper right corner, and choose "Publish with visitor authentication" in the Share to an audience section.
After enabling this option, you'll see a Private Key available for you to use. We'll need this later in our configuration, so leave this page open to grab this key later.
You'll also see your published space's url. This is the link users can access your published content—But since it's protected with Visitor Authentication, it'll return an error for anyone visiting this link without signing in first. We'll need this value in our configuration at a later point as well.
Next, we'll need to configure our Clerk account.
Sign up for Clerk
We are using Clerk in this demo to manage user authentication. You're able to sign up for a free account, which will allow you to follow along with the rest of this guide.
Once you have an account, you're able to create a free application, and configure the login experience for your users. You can choose from a large list of providers, or allow them to create a new account via email or phone number!
After you've customized your sign up/in screen you'll need to grab our API keys for this project.
Generate an API Key
Head to the API Keys section in the left side navigation to find keys specific for this project. We're using Next.js for the framework of this app, so you should see the following information at the top:
We'll need these in order to run the project. In your local project, you'll find an example
.env.example file that we'll use for our environment variables.
Rename this file to
.env, and replace the
CLERK_SECRET_KEY keys with the copied values from your Clerk dashboard.
.env file, you'll also see another key called
NEXT_PUBLIC_GITBOOK_URL. This is the URL that your site is published under, which can be found when you Publish your GitBook Site with Visitor Authentication.
At this point, your
.env file should look like this:
# Replace this with the public URL of the GitBook space you're protecting using Visitor Authentication.
# Copy these from the API keys sections in your Clerk application dashboard, by choosing "Next.js"
Finally, we'll need to configure one more section to complete the set up.
Create a Clerk Template
In the Clerk dashboard, head to the JWT Templates section in the left side navigation. You'll need to create a new template for your app to use.
Go to your Clerk dashboard.
In your Clerk application, go to JWT templates.
Create a new template using the "Blank" template.
Give your template a name (this demo uses
'). If you use a different name, make sure your template name matches the one set in
pages/api/visitor-auth.tsin your local project.
We'll now need the JWT key we created in Publish your GitBook Space with Visitor Authentication.
Enable the "Custom signing key" and select the HS256 algorithm.
Paste your private key in Clerk's JWT template Signing key field.
Lastly, we'll need to define a custom template for our sign in. Copy and paste the following code template into the "Claims" section.
Finally, click "Apply changes" to save your configuration.
Run and test project
Now that we have our configuration completed, we can run and test the Visitor Authentication flow. If you try to visit your published GitBook site direclty, you'll be met with a 401 screen—But if we go through the Visitor Authentication flow, we'll be able to access the site without a problem.
In the root of your project, run
npm run dev in the terminal. Then, navigate to the url your app is running on (by default, it should be
Here, you can sign up for an account.
After we sign in successfully, we'll then be able to navigate to our published site without any problems.
Visitor Authentication allows you to protect published GitBook sites behind a sign-in flow that you control.
Not only is it customizable, but it also opens up the door for many more possibilities in the future around the way you want to work in GitBook. Make sure to head to the Visitor Authentication docs to learn more.
Stay up to date
Interested in hearing more? Sign up for our newsletter below: