Identity & Access Management

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

PATCH
/scopes/{scopeId}/iam/sso

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Header Parameters

If-Match?string

ETag for optimistic concurrency on mutations/deletes; mismatch results in 412.

Request Body

application/json
  1. body

Editable subset of the SSO configuration ("Save configuration" form). Server-managed fields (acsUrl, domains, lastSync) are not accepted.

enabled?boolean
protocol?SsoProtocol

SSO / identity-provider protocol.

Value in"SAML""OIDC"
displayName?string
idpMetadataUrl?string
entityId?string
certificate?string

X.509 public signing certificate (PEM).

disableLocalPassword?boolean

Response Body

Configuration saved; returns the persisted SSO configuration.

application/json
  1. response

Tenant Single Sign-On configuration as rendered by the SSO page. Certificate is the public signing cert only.

enabled*boolean

Whether members from verified domains are redirected to the IdP.

protocol*SsoProtocol

SSO / identity-provider protocol.

Value in"SAML""OIDC"
displayName*string

Shown on the sign-in button, e.g. "Acme Okta".

idpMetadataUrl*string

Federation metadata endpoint from the IdP.

entityId*string

SP entity ID / issuer.

acsUrl*string

Server-managed ACS (Reply) URL to give the IdP administrator.

certificate*string

X.509 public signing certificate (PEM) used to validate IdP assertions.

disableLocalPassword*boolean

Force all members through SSO; break-glass owner accounts remain exempt.

lastSync*string

Last successful metadata sync from the IdP.

Formatdate-time
domains*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"  ]}