Organisations

Set up an OpenID Connect identity provider

Stores the issuer, the client id and the client secret after checking the issuer's discovery document.

PUT/orgs/{org}/sso/connection

TL;DR

Question	Answer
What does it do?	Set up an OpenID Connect identity provider.
What does it take?	A JSON body of type `SsoConnectionBody`.
What does it return?	Status 200 with a body of type `SsoConnection`.
What can go wrong?	`400` the body is not valid, or the secret is missing the first time (sso.invalid); `401` not signed in; `403` a member or a reader (orgs.forbidden), a plan without single sign-on (plan.sso_not_included), or the request came from an origin that may not make changes; `404` no such organisation, or the caller is not a member of it; `422` the issuer's discovery document cannot be used (sso.discovery_failed); `429` too many requests; `503` single sign-on is not set up on this server (sso.unavailable), or organisations are not. Every failure uses the one error envelope.

What it does

Stores the issuer, the client id and the client secret after checking the issuer's discovery document. The secret is required the first time, sealed, and never returned. A new connection is off until it is turned on. Enterprise; the owner and admins.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.

Request body

The body has the type SsoConnectionBody.

Field	Type	Required	Description
`issuer`	`string`	yes	The issuer URL of your own tenant. at least 9 characters; at most 300 characters.
`clientId`	`string`	yes	at least 1 character; at most 255 characters.
`clientSecret`	`string`	no	Required the first time. Left out later, the stored one is kept. Never returned. at least 1 character; at most 1000 characters.

Responses

Status	Meaning	Body
200	The connection.	`SsoConnection`
400	The body is not valid, or the secret is missing the first time (sso.invalid).	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	A member or a reader (orgs.forbidden), a plan without single sign-on (plan.sso_not_included), or the request came from an origin that may not make changes.	`ErrorResponse`
404	No such organisation, or the caller is not a member of it.	`ErrorResponse`
422	The issuer's discovery document cannot be used (sso.discovery_failed).	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Single sign-on is not set up on this server (sso.unavailable), or organisations are not.	`ErrorResponse`

Response body

A 200 answer has the type SsoConnection.

Field	Type	Required	Description
`protocol`	`"oidc" \| "saml"`	yes	OpenID Connect or SAML 2.0. One connection, one protocol.
`issuer`	`string`	yes	The OpenID Connect issuer, or the SAML provider's entity id.
`clientId`	`string \| null`	yes	OpenID Connect only.
`secretSet`	`boolean`	yes	True when an OpenID Connect client secret is stored. It is never returned. Always false for SAML.
`tokenAuthMethod`	`"client_secret_basic" \| "client_secret_post" \| null`	yes
`saml`	`SamlConnection`	yes	SAML only.
`saml.entityId`	`string`	yes	The provider's entity id, which every `Issuer` must equal.
`saml.ssoUrl`	`string`	yes	The provider's sign-in service on the redirect binding.
`saml.certificates`	`object[]`	yes
`saml.certificates[].fingerprint`	`string`	yes	SHA-256 of the certificate, as providers show it.
`saml.certificates[].notAfter`	`integer`	yes	When the certificate expires, in milliseconds since the epoch. Shown, not enforced.
`saml.emailAttribute`	`string \| null`	yes	The attribute that carries the address, or null when the name identifier does.
`saml.metadataUrl`	`string \| null`	yes	Where the metadata was fetched from, or null when it was pasted.
`enabled`	`boolean`	yes
`requireSso`	`boolean`	yes
`jit`	`boolean`	yes
`jitRole`	`"member" \| "reader"`	yes
`updatedAt`	`integer`	yes

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools