Update an identity provider connection

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

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$
idpConnectionIdstringRequired

The unique id of the identity provider connection

Body
labelstring · min: 1 · max: 100Optional

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

providerstring · enumOptional

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:
defaultTeamstring · nullableOptional

Team to add members to, or null to add them to none.

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
200

Connection updated

application/json

A connection to an identity provider, which signs organization members in with SAML and provisions them with SCIM.

objectstring · enumRequired

The object type, which is always "idp-connection"

Possible values:
idstringRequired

Unique identifier of the connection

labelstring · min: 1 · max: 100Required

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

providerstring · enumRequired

Identity provider behind the connection.

Possible values:
statusstring · enumRequired

Status of the connection.

  • pending: GitBook hasn't seen the identity provider use the connection yet.
  • ready: A member signed in with SAML through the connection, or the identity provider sent an authenticated SCIM request.
Possible values:
defaultRoleone of · nullableRequired

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:
defaultTeamFromDomainbooleanRequired

Whether people join the team of the verified email domain they signed in with, instead of defaultTeam.

createdAtstring · date-timeRequired

Date of creation

updatedAtstring · date-timeRequired

Date of the last update

patch/orgs/{organizationId}/idp-connections/{idpConnectionId}
PATCH /v1/orgs/{organizationId}/idp-connections/{idpConnectionId} 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"
  ]
}
{
  "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"
  }
}

Last updated

Was this helpful?

Powered by GitBook