Create a new SAML provider

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$
Body
labelstring · min: 1 · max: 30Required
entityIDstring · max: 1024Optional
certificatestring · max: 10000Optional
ssoURLstring · uri · max: 2048Optional
defaultTeamstringOptional
defaultTeamFromDomainbooleanOptional
defaultRoleone of · nullableOptional

Role given to people on their first sign-in through the provider. null adds them as guests, "default" uses the organization's default role, and "domain" uses the role of the verified email domain they signed in with.

string · enumOptional

"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.

Possible values:
domainsstring[] · max: 50Optional

Email domains the provider signs people in for. Each one must be an email domain of the organization. Only emails on a verified domain in this list can sign in through the provider.

Responses
201

SAML Provider created

application/json
post/orgs/{organizationId}/saml
POST /v1/orgs/{organizationId}/saml HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "label": "text",
  "entityID": "text",
  "certificate": "text",
  "ssoURL": "https://example.com",
  "defaultTeam": "text",
  "defaultTeamFromDomain": true,
  "defaultRole": "admin",
  "domains": [
    "text"
  ]
}
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": "2026-01-01T00:00:00.000Z",
    "permissions": {
      "admin": true,
      "view": true
    }
  },
  "defaultTeamFromDomain": true,
  "defaultRole": "admin",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "status": "active",
  "domains": [
    {
      "domain": "text",
      "status": "verified"
    }
  ],
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

Last updated

Was this helpful?

Powered by GitBook