Skip to content
Dashboard
Theme
Theme

Start a test sign-in

POST /v1/connections/{conn}/test: Start a test sign-in.

View Markdown

POST /v1/connections/{conn}/test

The response’s attempt_id names this attempt; the test result carries the same ID once it is recorded, so a caller can ignore an earlier attempt’s result. scenario picks one of the sandbox test IdP’s outcomes and is accepted only in a sandbox environment (sandbox_required elsewhere) on a connection whose IdP is the test IdP (test_idp; parameter_invalid otherwise). time_shift and certificate follow the same rules.

Scope
connections:write
Auth
Secret key (sk_…)
Since
1.0
  • conn string Required

  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • Idempotency-Key string

    Honoured for 24 h; a replay returns the original response.

    min length 1 · max length 255

  • scenario string

    A sandbox test IdP outcome (sandbox environments and test IdP connections only). rotated_cert signs with the test IdP’s rotated key (refused with saml_signature_invalid until the connection trusts the rotated certificate) and expiring_cert with a key whose certificate expires within days, so a certificate rollover and the expiry alerts can be rehearsed; revoked_user is the IdP refusing a user whose access it revoked (saml_idp_status_error, or oidc_token_exchange_failed for OIDC).

    one of sp_initiated, idp_initiated, guest_domain, bad_signature, expired, wrong_audience, missing_email, rotated_cert, expiring_cert, revoked_user

  • time_shift string

    Time travel for the sandbox test IdP (sandbox environments and test IdP connections only), a duration such as -10m or 2h, at most 24h either way. Only the test IdP’s clock moves; documents outside the broker’s skew allowance are refused as they would be from a real IdP with a wrong clock.

    max length 16

  • certificate string

    The certificate the sandbox test IdP signs with (sandbox environments and test IdP connections only). rotated and expiring let a certificate rollover be rehearsed with any scenario; with rotated_cert or expiring_cert it must name that scenario’s key (parameter_invalid otherwise).

    one of current, rotated, expiring

Errors share one shape; see the error code catalogue.

curl -X POST \
"https://api.ohauthcat.com/v1/connections/conn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/test" \
-H "Authorization: Bearer $OHAUTHCAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scenario": "sp_initiated",
"time_shift": "-10m",
"certificate": "current"
}'
Response 200
{
"test_url": "https://app.acme.com/callback",
"expires_at": "2026-01-15T09:30:00Z",
"attempt_id": "sgn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"started_at": "2026-01-15T09:30:00Z"
}