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.
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.
- 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.
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!
Let's build the key workflows you'll need:
When a new user joins your organization, you need to provision them in GitBook.
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": [
],
"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.
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.
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'
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": [
],
"remove": [
]
}'
All of the above operations are idempotent - you can run them multiple times and put them behind retry logic.
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!
Last modified 6mo ago