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.
A unique entity identifier
^[a-zA-Z0-9_-]+$Name of the identity provider connection, shown to organization admins.
Identity provider behind the connection.
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.
"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.
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.
Connection created
An identity provider connection, with the SCIM token the request created. The token can't be retrieved again.
SCIM bearer token to configure in the identity provider.
Bad Request
Not Found
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?