Create an identity provider connection

Creates a connection with its SAML service provider URLs and a SCIM token. The token is only returned in this response.

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: 100Required

Name of the identity provider connection, shown to organization admins.

providerstring · enumRequired

Identity provider behind the connection.

Possible values:
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:
defaultTeamstringOptional
defaultTeamFromDomainbooleanOptional
ssoURLstring · uri · max: 2048Optional
entityIDstring · max: 1024Optional
certificatestring · max: 10000Optional
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

Connection created

application/json

An identity provider connection, with the SCIM token the request created. The token can't be retrieved again.

tokenstringRequired

SCIM bearer token to configure in the identity provider.

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

{
  "label": "text",
  "provider": "okta",
  "defaultRole": "admin",
  "defaultTeam": "text",
  "defaultTeamFromDomain": true,
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "domains": [
    "text"
  ]
}
{
  "connection": {
    "object": "idp-connection",
    "id": "text",
    "label": "text",
    "provider": "okta",
    "status": "pending",
    "defaultRole": "admin",
    "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,
    "saml": {
      "ssoURL": "https://example.com",
      "entityID": "text",
      "certificate": "text",
      "domains": [
        {
          "domain": "text",
          "status": "verified"
        }
      ],
      "service": {
        "acsURL": "https://example.com",
        "startURL": "https://example.com",
        "entityID": "text"
      },
      "lastUsedAt": "2026-01-01T00:00:00.000Z"
    },
    "scim": {
      "baseURL": "https://example.com",
      "tokenHint": "text",
      "tokenCreatedAt": "2026-01-01T00:00:00.000Z",
      "lastUsedAt": "2026-01-01T00:00:00.000Z"
    },
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "urls": {
      "location": "https://example.com"
    }
  },
  "token": "text"
}

Last updated

Was this helpful?

Powered by GitBook