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.

Re-sync federation metadata from the IdP

POST
/scopes/{scopeId}/iam/sso/actions/refresh

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.

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

Idempotency-Key?string

Optional; 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.

Formatuuid

Response Body

Metadata re-synced; returns the refreshed configuration with updated lastSync.

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 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"  ]}