The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

SSO

Configure Single Sign-On solutions to unify your organization’s authentication.

Tie GitBook into your corporate identity management and authentication providers (like SAML or OAuth). This centralizes user authentication and improves security.

The Subdomain object

Attributes
objectstring · enumrequiredAvailable options:
subdomainstring · min: 3 · max: 32required

The GitBook subdomain, for example "my-company" in "my-company.gitbook.io"

Pattern: ^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$
targetone ofrequired

isActivebooleanrequired

The Subdomain object

{
  "object": "subdomain",
  "subdomain": "text",
  "target": {
    "type": "organization",
    "organization": "text"
  },
  "isActive": true
}

List all SAML providers

get

Lists SAML providers configured for the specified organization.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "saml-provider",
      "id": "text",
      "label": "text",
      "ssoURL": "https://example.com",
      "entityID": "text",
      "certificate": "text",
      "defaultTeam": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-04-12T21:04:01.096Z"
      },
      "defaultRole": "admin",
      "createdAt": "2025-04-12T21:04:01.096Z",
      "service": {
        "acsURL": "https://example.com",
        "startURL": "https://example.com",
        "entityID": "text"
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

OK

Create a new SAML provider

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
labelstring · min: 1 · max: 30required
entityIDstring · max: 1024optional
certificatestring · max: 10000optional
ssoURLstring · uri · max: 2048optional
defaultTeamstringoptional
defaultRoleone ofoptional

The role of a member in an organization, null for guests

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "text",
    "entityID": "text",
    "certificate": "text",
    "ssoURL": "https://example.com",
    "defaultTeam": "text",
    "defaultRole": "admin"
  }'
{
  "object": "saml-provider",
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "object": "team",
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-04-12T21:04:01.096Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-04-12T21:04:01.096Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

SAML Provider created

Get a SAML provider by its ID

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml/{samlProviderId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "saml-provider",
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "object": "team",
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-04-12T21:04:01.096Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-04-12T21:04:01.096Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

OK

Delete a SAML provider

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml/{samlProviderId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

SAML provider has been deleted

Update a SAML provider

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Body
labelstring · min: 1 · max: 30optional
entityIDstring · max: 1024optional
certificatestring · max: 10000optional
ssoURLstring · uri · max: 2048optional
defaultTeamstringoptional
defaultRoleone ofoptional

The role of a member in an organization, null for guests

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml/{samlProviderId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "text",
    "entityID": "text",
    "certificate": "text",
    "ssoURL": "https://example.com",
    "defaultTeam": "text",
    "defaultRole": "admin"
  }'
{
  "object": "saml-provider",
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "object": "team",
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-04-12T21:04:01.096Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-04-12T21:04:01.096Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

SAML provider has been updated

List all SSO provider login infos

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sso' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "id": "text",
      "label": "text",
      "startURL": "https://example.com"
    }
  ]
}

OK

Was this helpful?