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.

Test the SSO connection to the IdP

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

Runs a connectivity and configuration test against the configured identity provider (UI "Test connection" in the Identity provider panel). The backend resolves the IdP metadata URL, validates the entity ID / issuer match and checks that the configured X.509 certificate can validate a sample assertion, returning a success/failure verdict with a human-readable message — the UI surfaces it as a toast such as "Connection test succeeded — IdP reachable". The test never mutates the stored configuration. Validation: an SSO configuration must exist for the tenant (else 404 NOT_FOUND); SSO must be enabled — the UI hints "Enable SSO to test" and a disabled connection → 409 CONFLICT; caller must be tenant owner|admin else 403 FORBIDDEN. Async & state: Synchronous probe — 200 with an SsoConnectionTestResult capturing success, message and testedAt. No resource state change and no SSE frames; an unreachable IdP is reported inside the 200 result as success: false rather than a transport error. Errors: 401 unauthenticated; 403 not a tenant owner/admin; 404 no SSO configuration in scope; 409 CONFLICT when SSO is disabled; 429 the test endpoint is rate-limited to protect the IdP; 500 unexpected probe infrastructure failure. Idempotency/Concurrency: Idempotency-Key is optional (recommended) since the UI can retry the POST; replay returns the original test verdict without re-probing the IdP. No If-Match — nothing is mutated.

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

Test executed; verdict and message describe the outcome (including reachable-but-misconfigured cases).

application/json
  1. response

Verdict from the "Test connection" probe. Failures are reported here, not as transport errors.

success*boolean
message*string

Human-readable outcome, e.g. "Connection test succeeded — IdP reachable".

testedAt*string
Formatdate-time
curl -X POST "https://example.com/scopes/string/iam/sso/actions/test"
{  "success": true,  "message": "string",  "testedAt": "2019-08-24T14:15:22Z"}