Guide: Directory Sync using the GitBook API

This guide will help you set up a directory sync for provisioning users and teams using the GitBook API.

1. Getting Started

First of all, you'll need to be set up and accustomed to working with the GitBook API.

2 .Setting up your environment

First, let's understand from a high-level how user provisioning works:

A high-level overview of how user provisioning works

The step in purple will change depending on your Identity Provider (IdP). Most modern directories offer workflows to hook into events like users adding/leaving your organization, but you might have to build this piece yourself.

IdPs that support automation out of the box

• Okta supports this through Okta Workflows. Their documentation features an example of using Okta Workflows to send an HTTP request when an event happens in your directory.

Your API Key

You'll need to make sure you've generated a valid API key and that you're an adminstrator of the target GitBook organization. For now, API keys are generated per user (so if you leave your GitBook organization you'll need another admin to use their key) - though we are looking at organization API keys!

3. Building the Workflows

Let's build the key workflows you'll need:

Provision a new user

When a new user joins your organization, you need to provision them in GitBook.

To do this, we'll use the invites endpoint.

curl --location 'https://api.gitbook.com/v1/orgs/$YOUR_ORG_KEY/invites' \
--header 'Authorization: Bearer $YOUR_GITBOOK_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "emails": [
        "[e-mail]"
    ],
    "role": "read",
    "sso": true
}'

Make sure you've included sso in the body so that the user is created as a proper SSO user, and the appropriate role for the user.

If you're batching users together, this endpoint accepts a list of emails.

Storing the response

The API will tell you the ID of this newly created user:

{
    "users": [
        "PERerEOAQ6QWXj1flmrlVzl3XJ22"
    ],
    "invited": 0
}

If you can, try to save this user ID alongside the user in your directory. It'll help when we run future operations.

Deprovision/remove a user

When a user leaves your organization, you need to remove them from GitBook. You'll need the GitBook ID of the user who's leaving, which ideally would be saved alongside the user in your directory.

If you can't save the user ID alongside your directory user, please get in touch with our support team.

We'll then use the remove member endpoint to remove the user:

curl --location --request DELETE 'https://api.gitbook.com/v1/orgs/$YOUR_ORG_ID/members/$USER_ID' \
--header 'Authorization: Bearer $YOUR_GITBOOK_API_KEY'

Add/remove a user to/from a team

When group memberships change in your organization, you'll want to replicate these changes in GitBook. We have a single API endpoint for this, where team members can be added/removed in one call.

curl --location --request PUT 'https://api.gitbook.com/v1/orgs/$YOUR_ORG_ID/teams/$TEAM_ID/members' \
--header 'Authorization: Bearer $YOUR_GITBOOK_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "add": [
        "[e-mail]"
    ],
    "remove": [
        "[e-mail]"
    ]
}'

Idempotency

All of the above operations are idempotent - you can run them multiple times and put them behind retry logic.

Usage Limits

The GitBook API has some usage limits to prevent malicious users abusing the system. If you're on our enterprise plan, you won't face these limits. However, if you're on one of our other plans and you're running into rate-limiting errors with the API please get in touch so we can remove these limits for you.

We're always trying to improve our API to enable more complex workflows tailored to your organization. If you have feedback for us around ways the API could be improved, please let us know via our community!