SSO connections

Create an SSO connection

Creates an SSO connection. Requires sso:manage and the sso feature. Create it inactive, hand the returned urls to the IdP administrator, then activate it with PATCH — activation is refused while the protocol's required config is incomplete. Domains are attached separately, by pointing an org domain at this connection with PATCH /org-domain/{id}. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers 428 step_up_required). An organization API token is not challenged.

post/sso-connection

Request

  • Base URL: https://api.elaichi.ai
  • URL: https://api.elaichi.ai/sso-connection
  • Auth: HTTP bearer

Headers

X-Organization-Idstring

Target organization (org_…). Required for cookie/session auth on org-scoped routes; optional for API tokens, which carry their organization, and rejected when it names a different one.

Request body

protocol'oidc' | 'saml' required

Immutable after creation.

namestring required
is_activeboolean
enforcedboolean

See enforced on the response — this locks users to the IdP.

is_defaultboolean
client_secretstring

OIDC client secret. Write-only — stored encrypted, never returned.

default_role_idstring nullable

Role id (role_…).

Response

Created

idstring

SSO connection id (sso_…).

organization_idstring

Owning organization (org_…).

protocol'oidc' | 'saml'
namestring
is_activeboolean

A draft may be saved incomplete, but cannot be activated until the protocol's required fields are present.

enforcedboolean

When enforced, users on the connection's verified domains can ONLY sign in through this IdP — social login and email codes are refused for them.

is_defaultboolean

The connection domain resolution picks when a domain has several.

default_role_idstring nullable

Role (role_…) explicitly configured for users provisioned through this connection, or null to track the default. Org Owner is refused here. Read effective_default_role_id to learn what a JIT login actually grants.

effective_default_role_idstring nullable

Server-computed: the role SSO just-in-time provisioning through this connection really grants. Equals default_role_id when that is set and the role still exists; otherwise the Member system role, which is what the join falls back to both when nothing is configured and when the configured role has since been deleted. null means even that fallback is missing, so auto-provisioning through this connection is broken and the first login seats nobody.

has_client_secretboolean

Whether an OIDC client secret is stored. The secret itself is never returned.

urlsobject

The protocol URLs to hand to the IdP administrator (ACS / metadata / callback, by protocol).

created_atstring date-time
updated_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.