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.
Re-sync federation metadata from the IdP
Re-fetches the federation metadata document from the configured IdP metadata URL and refreshes the cached
signing certificate, endpoints and issuer details (UI "Re-sync metadata" in the Status panel; toast
"Metadata re-synced from IdP"). On success lastSync is updated and the Status panel reflects the new sync
time. This keeps assertion validation working across IdP certificate rollovers without manual re-entry.
Validation: an SSO configuration must exist for the tenant (else 404 NOT_FOUND); SSO must currently be
enabled with a configured idpMetadataUrl — refreshing a disabled or unconfigured connection → 409 CONFLICT;
caller must be tenant owner|admin else 403 FORBIDDEN. An unreachable or invalid metadata endpoint surfaces as
a failed result, not a silent success.
Async & state: Synchronous command — 200 with the refreshed SsoConfiguration (updated lastSync and, if
rolled, certificate). Emits a resource.updated SSE frame (kind: iam.sso_configuration, patch: {lastSync,
certificate}). No transitional states.
Errors: 401 unauthenticated; 403 not a tenant owner/admin; 404 no SSO configuration in scope; 409
CONFLICT when SSO is disabled/unconfigured; 422 the IdP metadata document fetched is malformed or fails
signature checks; 500 metadata fetch/persistence failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same
key returns the original refresh
result instead of re-contacting the IdP, making UI retries safe.
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.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidMetadata re-synced; returns the refreshed configuration with updated lastSync.
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 POST "https://example.com/scopes/string/iam/sso/actions/refresh"{ "enabled": true, "protocol": "SAML", "displayName": "string", "idpMetadataUrl": "string", "entityId": "string", "acsUrl": "string", "certificate": "string", "disableLocalPassword": true, "lastSync": "2019-08-24T14:15:22Z", "domains": [ "string" ]}