Skip to content
Dashboard
Theme
Theme

Explain a failed sign-in

GET /v1/sign_ins/{sign_in}/explanation: Explain a failed sign-in.

View Markdown

GET /v1/sign_ins/{sign_in}/explanation

A plain-language explanation of why the sign-in failed. When a language-model provider is configured for the deployment, the explanation is written from redacted catalog data only (the error code, the names of the checks that ran and the IdP type; never an email, assertion, token or address) and cached per failure signature. Otherwise, or when the provider fails, source is doctor and the text is the Doctor’s deterministic cause and steps. A sign-in that did not fail has error_code: null. When the environment’s monthly explanation cost cap is reached, or too many explanations are asked for in a short window, the Doctor text is served and unavailable_reason says why (explanation_budget_exhausted, explanation_rate_limited; the same codes as the error catalogue). Explanations are opt-in per account: until an account admin turns them on (explain_enabled on the account), the provider is never called and the Doctor text is served with explain_enabled false.

Scope
workbench:read
Auth
Secret key (sk_…)
Since
1.0
  • sign_in string Required

  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

Errors share one shape; see the error code catalogue.

curl -X GET \
"https://api.ohauthcat.com/v1/sign_ins/sgn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/explanation" \
-H "Authorization: Bearer $OHAUTHCAT_API_KEY"
Response 200
{
"sign_in_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"error_code": "saml_signature_invalid",
"source": "doctor",
"provider": "okta",
"model": "example_model",
"unavailable_reason": "explanation_budget_exhausted",
"explain_enabled": true,
"text": "example_text"
}