Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Save the SSO configuration
Updates the tenant's Single Sign-On configuration (UI "Save configuration"). Editable fields mirror the
the SSO page form: enablement, protocol (SAML 2.0 / OIDC), display name, IdP metadata URL, entity ID / issuer,
the X.509 signing certificate, and the "disable local password sign-in" security policy. Server-managed
fields (acsUrl, verified domains, lastSync) cannot be changed here. Enforcing disableLocalPassword forces
all members through SSO while break-glass owner accounts remain exempt — the UI warns to verify a break-glass
login first.
Validation: all IdP fields (protocol, displayName, idpMetadataUrl, entityId, certificate) are required
when enabled: true — missing/blank → 422 VALIDATION_FAILED; idpMetadataUrl must be a well-formed HTTPS
URL and certificate a parseable X.509 PEM block → 422; disableLocalPassword: true is rejected with 409
CONFLICT when no owner has a verified break-glass login; attempts to set server-managed fields → 422; caller
must be tenant owner|admin else 403 FORBIDDEN.
Async & state: Synchronous mutation — 200 with the persisted configuration; the connection status pill
flips between Connected/Not configured immediately. Emits a resource.updated SSE frame
(kind: iam.sso_configuration, patch: {enabled, protocol, displayName, disableLocalPassword}).
Errors: 401 unauthenticated; 403 not a tenant owner/admin; 404 scope not found; 409 CONFLICT enforcing
SSO-only sign-in without a verified break-glass owner; 412 If-Match mismatch on concurrent edit; 422 invalid
or non-editable fields; 500 persistence failure.
Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted
and a sent one is ignored. A repeated identical PATCH saves the same configuration again (same
end state) and advances updatedAt, which changes the ETag, so resending a request that already
succeeded with its original If-Match gets 412. If-Match with the ETag from the list read
prevents overwriting a concurrent configuration change.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
If-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
application/json- body
Editable subset of the SSO configuration ("Save configuration" form). Server-managed fields (acsUrl, domains, lastSync) are not accepted.
enabled?booleanprotocol?SsoProtocolSSO / identity-provider protocol.
"SAML""OIDC"displayName?stringidpMetadataUrl?stringentityId?stringcertificate?stringX.509 public signing certificate (PEM).
disableLocalPassword?booleanConfiguration saved; returns the persisted SSO configuration.
application/json- response
Tenant Single Sign-On configuration as rendered by the SSO page. Certificate is the public signing cert only.
enabled*booleanWhether members from verified domains are redirected to the IdP.
protocol*SsoProtocolSSO / identity-provider protocol.
"SAML""OIDC"displayName*stringShown on the sign-in button, e.g. "Acme Okta".
idpMetadataUrl*stringFederation metadata endpoint from the IdP.
entityId*stringSP entity ID / issuer.
acsUrl*stringServer-managed ACS (Reply) URL to give the IdP administrator.
certificate*stringX.509 public signing certificate (PEM) used to validate IdP assertions.
disableLocalPassword*booleanForce all members through SSO; break-glass owner accounts remain exempt.
lastSync*stringLast successful metadata sync from the IdP.
date-timedomains*array<string>Verified email domains federated through this connection.
curl -X PATCH "https://example.com/scopes/string/iam/sso" \ -H "Content-Type: application/json" \ -d '{}'{ "enabled": true, "protocol": "SAML", "displayName": "string", "idpMetadataUrl": "string", "entityId": "string", "acsUrl": "string", "certificate": "string", "disableLocalPassword": true, "lastSync": "2019-08-24T14:15:22Z", "domains": [ "string" ]}