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 GitBook subdomain, for example "my-company" in "my-company.gitbook.io"
^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$The Subdomain object
{
"object": "subdomain",
"subdomain": "text",
"target": {
"type": "organization",
"organization": "text"
},
"isActive": true
}Lists SAML providers configured for the specified organization.
The unique id of the organization
Identifier of the page results to fetch.
The number of results per page
GET /v1/orgs/{organizationId}/saml HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
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-06-21T04:17:27.385Z",
"permissions": {
"admin": true,
"view": true
}
},
"defaultRole": "admin",
"createdAt": "2025-06-21T04:17:27.385Z",
"status": "active",
"service": {
"acsURL": "https://example.com",
"startURL": "https://example.com",
"entityID": "text"
},
"urls": {
"location": "https://example.com"
}
}
]
}The unique id of the organization
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.
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"
}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-06-21T04:17:27.385Z",
"permissions": {
"admin": true,
"view": true
}
},
"defaultRole": "admin",
"createdAt": "2025-06-21T04:17:27.385Z",
"status": "active",
"service": {
"acsURL": "https://example.com",
"startURL": "https://example.com",
"entityID": "text"
},
"urls": {
"location": "https://example.com"
}
}The unique id of the organization
The unique id of the SAML provider
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-06-21T04:17:27.385Z",
"permissions": {
"admin": true,
"view": true
}
},
"defaultRole": "admin",
"createdAt": "2025-06-21T04:17:27.385Z",
"status": "active",
"service": {
"acsURL": "https://example.com",
"startURL": "https://example.com",
"entityID": "text"
},
"urls": {
"location": "https://example.com"
}
}The unique id of the organization
The unique id of the SAML provider
DELETE /v1/orgs/{organizationId}/saml/{samlProviderId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
SAML provider has been deleted
No content
The unique id of the organization
The unique id of the SAML provider
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.
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"
}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-06-21T04:17:27.385Z",
"permissions": {
"admin": true,
"view": true
}
},
"defaultRole": "admin",
"createdAt": "2025-06-21T04:17:27.385Z",
"status": "active",
"service": {
"acsURL": "https://example.com",
"startURL": "https://example.com",
"entityID": "text"
},
"urls": {
"location": "https://example.com"
}
}The unique id of the organization
GET /v1/orgs/{organizationId}/sso HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
OK
{
"items": [
{
"id": "text",
"label": "text",
"startURL": "https://example.com"
}
]
}Was this helpful?