Organisations
Read an organisation's single sign-on settings
The connection to the identity provider (never the client secret), the email domains with the DNS record each needs, the redirect URI to register, and whether the plan has single sign-on.
GET
/orgs/{org}/ssoTL;DR
| Question | Answer |
|---|---|
| What does it do? | Read an organisation's single sign-on settings. |
| What does it take? | org in the path. |
| What does it return? | Status 200 with a body of type SsoSettings. |
| What can go wrong? | 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; 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
The connection to the identity provider (never the client secret), the email domains with the DNS record each needs, the redirect URI to register, and whether the plan has single sign-on. The owner and admins only.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | SsoSettings |
| 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 |
| 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 SsoSettings.
| Field | Type | Required | Description |
|---|---|---|---|
available | boolean | yes | Whether the organisation's plan has single sign-on (Enterprise). |
plan | "free" | "pro" | "enterprise" | yes | |
redirectUri | string | yes | The redirect URI to register at the identity provider. |
saml | SamlServiceProvider | yes | |
saml.entityId | string | yes | Our entity id for this organisation: the audience to set at the provider. |
saml.acsUrl | string | yes | Our assertion consumer service for this organisation: the single sign-on URL to set at the provider. |
saml.metadataUrl | string | yes | Our service provider metadata, for a provider that imports it. |
samlAvailable | boolean | yes | Whether this server can check SAML responses. |
connection | SsoConnection | yes | |
connection.protocol | "oidc" | "saml" | yes | OpenID Connect or SAML 2.0. One connection, one protocol. |
connection.issuer | string | yes | The OpenID Connect issuer, or the SAML provider's entity id. |
connection.clientId | string | null | yes | OpenID Connect only. |
connection.secretSet | boolean | yes | True when an OpenID Connect client secret is stored. It is never returned. Always false for SAML. |
connection.tokenAuthMethod | "client_secret_basic" | "client_secret_post" | null | yes | |
connection.saml | SamlConnection | yes | SAML only. |
connection.saml.entityId | string | yes | The provider's entity id, which every Issuer must equal. |
connection.saml.ssoUrl | string | yes | The provider's sign-in service on the redirect binding. |
connection.saml.certificates | object[] | yes | |
connection.saml.emailAttribute | string | null | yes | The attribute that carries the address, or null when the name identifier does. |
connection.saml.metadataUrl | string | null | yes | Where the metadata was fetched from, or null when it was pasted. |
connection.enabled | boolean | yes | |
connection.requireSso | boolean | yes | |
connection.jit | boolean | yes | |
connection.jitRole | "member" | "reader" | yes | |
connection.updatedAt | integer | yes | |
domains | SsoDomain[] | yes | |
domains[].id | string | yes | |
domains[].domain | string | yes | |
domains[].verified | boolean | yes | |
domains[].verifiedAt | integer | null | yes | |
domains[].checkedAt | integer | null | yes | |
domains[].createdAt | integer | yes | |
domains[].record | object | yes | |
domains[].record.name | string | yes | |
domains[].record.type | "TXT" | yes | |
domains[].record.value | string | yes |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |