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
application/json
all ofoptional
get
GET /v1/orgs/{organizationId}/saml HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "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-16T04:38:06.513Z"
      },
      "defaultRole": "admin",
      "createdAt": "2025-04-16T04:38:06.513Z",
      "service": {
        "acsURL": "https://example.com",
        "startURL": "https://example.com",
        "entityID": "text"
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

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
application/json
objectoptional
post
POST /v1/orgs/{organizationId}/saml HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 129

{
  "label": "text",
  "entityID": "text",
  "certificate": "text",
  "ssoURL": "https://example.com",
  "defaultTeam": "text",
  "defaultRole": "admin"
}
201

SAML Provider created

{
  "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-16T04:38:06.513Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-04-16T04:38:06.513Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

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
application/json
objectoptional
get
GET /v1/orgs/{organizationId}/saml/{samlProviderId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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-16T04:38:06.513Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-04-16T04:38:06.513Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

Delete a SAML provider

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Responses
delete
DELETE /v1/orgs/{organizationId}/saml/{samlProviderId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
204

SAML provider has been deleted

No Content

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
application/json
objectoptional
patch
PATCH /v1/orgs/{organizationId}/saml/{samlProviderId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 129

{
  "label": "text",
  "entityID": "text",
  "certificate": "text",
  "ssoURL": "https://example.com",
  "defaultTeam": "text",
  "defaultRole": "admin"
}
200

SAML provider has been updated

{
  "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-16T04:38:06.513Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-04-16T04:38:06.513Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

List all SSO provider login infos

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Responses
application/json
objectoptional
get
GET /v1/orgs/{organizationId}/sso HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "items": [
    {
      "id": "text",
      "label": "text",
      "startURL": "https://example.com"
    }
  ]
}

Was this helpful?