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
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.
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.
uuidTest executed; verdict and message describe the outcome (including reachable-but-misconfigured cases).
application/json- response
Verdict from the "Test connection" probe. Failures are reported here, not as transport errors.
success*booleanmessage*stringHuman-readable outcome, e.g. "Connection test succeeded — IdP reachable".
testedAt*stringdate-timecurl -X POST "https://example.com/scopes/string/iam/sso/actions/test"{ "success": true, "message": "string", "testedAt": "2019-08-24T14:15:22Z"}