API reference

API reference: SSO

Cloud Control per-organization OIDC SSO configuration API: read, create/update (with server-side discovery and an encrypted secret), and enable or disable single sign-on.

Per-organization OIDC configuration. The entire surface — reads included — is org-admin only (manage_users_sso) and session-only. The client secret is encrypted at rest and never returned.

GET/api/org/ssoOrg Admin (session only)

Return the org's SSO config (or null). The secret is never included — only a set flag.

Example response

json

{ "sso": { "type": "oidc", "issuer": "https://idp.example.com", "clientId": "cc-app",
  "clientSecretSet": true, "defaultRole": "Viewer", "emailDomains": ["acme.io"],
  "enabled": true, "updatedAt": "2026-07-01T10:00:00.000Z" } }

Errors

Status	When
`401`	Not signed in.
`403`	Caller lacks manage_users_sso.

POST/api/org/ssoOrg Admin (session only)

Create or update the OIDC config. Runs discovery against the issuer and stores resolved endpoints; enables SSO.

Parameters

Name	In	Required	Description
`issuer`	body	yes	IdP issuer URL (https).
`clientId`	body	yes	OIDC client id.
`clientSecret`	body	no	Client secret (required on first save; blank keeps existing on update).
`defaultRole`	body	no	Role for JIT users; defaults to Viewer.
`emailDomains`	body	no	Up to 20 domains routed to this IdP.

Example request

json

{ "issuer": "https://idp.example.com", "clientId": "cc-app", "clientSecret": "…", "defaultRole": "Viewer", "emailDomains": ["acme.io"] }

Example response

json

{ "ok": true, "sso": { "…": "as GET" } }

Errors

Status	When
`400`	Non-https issuer, missing client id, bad role, invalid domains, missing first-time secret, or discovery failure.
`403`	Caller lacks manage_users_sso.
`503`	The secret keyring (CC_DATA_KEY) isn't configured.

PATCH/api/org/ssoOrg Admin (session only)

Enable or disable SSO without changing the config.

Parameters

Name	In	Required	Description
`enabled`	body	yes	true or false.

Example request

json

{ "enabled": false }

Example response

json

{ "ok": true, "sso": { "enabled": false, "…": "…" } }

Errors

Status	When
`400`	`enabled` is not a boolean.
`403`	Caller lacks manage_users_sso.
`404`	SSO isn't configured yet.