Transferring an Organization
Transfer one organization into another, moving all of the members, teams, and content and preserving public content URLs.
The GitBook API is currently in beta. This means you should not rely on it's availability, and that it may change without prior warning. If you wish to be one of our testers, please contact our team at [email protected].
This is an experimental endpoint and unsupervised use could result in loss of content and/or public URLs breaking. Contact us at [email protected] if you're interested in this functionality and we'll help you through the process.
The transfer operation is irreversible. Content is moved from one organization to another, it is not duplicated or copied. It is not possible to undo a transfer operation.
Terminology
The source organization is the organization you are transferring all content from. The source organization will be empty once the transfer is complete.
The target organization is the organization you are transferring all content to.
Usage
You must be an administrator of both organizations to perform the transfer.
This is an experimental endpoint that is not currently publicly accessible. Contact us if you are in need of this functionality and we'll help you get set up.
Advanced
Members & Teams
All members and teams from the target organization will be migrated into the source organization, unless they already exist in the target (members of both organizations will be unaffected).
The organization-level permission of the transferred member depends on the
defaultOrgRole parameter:- If the
defaultOrgRoleis set to a valid GitBook permission (such aseditor,commenter, etc.), that value will be used as the permission for new organization members. - If the
defaultOrgRoleis set tosaml, then the role will be taken from the SAML provider of the target organization. If your target organization has SSO enabled, and adds new users ascommentersin the organization, then thecommenterrole will be used. - If the
defaultOrgRoleis not set, new members will havereadpermissions in the target organization.
If a member already exists in the target organization (i.e. they were a member of both source and target organizations before the transfer), their org-level permission will not change.
Content
All of your content will be moved to a new top-level collection in the target organization. This collection will have the name and icon of the source organization.
For example if you wanted to transfer the source organization "iPhone" into the target organization "Apple", there'd be a new collection called "iPhone" in the Apple organization once the transfer was complete.
The content-level permissions of the source organization will be transferred to this new collection. A user who was an editor in the target organization will be an editor of the top-level collection once the transfer is complete. All other permissions will be respected.
GitBook URLs and Paths
GitBook URLs (those that start with https://app.gitbook.com) and paths (such as
/product-documentation/guidelines) will continue to function as normally.Hostnames
If your source organization has some public content, it will have been assigned a GitBook hostname of the format
https://hostname.gitbook.ioWe'll transfer this hostname over to the new organization, so the gitbook.io URL will continue to work.
The source organization will have a new hostname generated on its behalf, this will be a non-conflicting hostname based on the previous. Imagine you had the following setup:
source.gitbook.io => the source organizationtarget.gitbook.io => the target organizationOnce the transfer was complete, the hostnames would be set up like so:
source.gitbook.io => the target organizationtarget.gitbook.io => the target organizationsource-1.gitbook.io => the source organization (now empty)It's possible that both your target and source organizations have content that use the same path (e.g.
target.gitbook.io/welcome and source.gitbook.io/welcome)This will cause a conflict when the transfer takes place and the path of the source organization will be reassigned.
Once the transfer is complete,
target.gitbook.io/welcome will point to the target organization's welcome space.source.gitbook.io/welcome will also point to the target organization's welcome space.source.gitbook.io/welcome-1 will point to the source organization's welcome space.For any users that still hold the old source URL, they'll be redirected to a space they may have never seen before.
In order to prevent this, ensure that there are no conflicting paths for public content in your source and target organizations.
Custom Domains
Any custom domains you have set up on the source organization will now direct to the newly created top-level collection in the target organization.
This should ensure your custom domains continue to point to the correct content.
Last modified 2mo ago
Copy link