Explain a failed sign-in
GET /v1/sign_ins/{sign_in}/explanation: Explain a failed sign-in.
GET /
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
Path parameters
Section titled “Path parameters”sign_instring Required
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Responses
Section titled “Responses”- 200 OK SignInExplanation
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 404 Code: resource_not_found (also returned for other tenants’ IDs); a path no endpoint serves answers route_not_found. A browser GET or HEAD of an unknown path whose Accept ranks text/html above JSON gets an HTML 404 page instead, with the same status; every other client gets this JSON body. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
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"const response = await fetch("https://api.ohauthcat.com/v1/sign_ins/sgn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/explanation", { method: "GET", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, },});const data = await response.json();import osimport requests
response = requests.get( "https://api.ohauthcat.com/v1/sign_ins/sgn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/explanation", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"},)data = response.json(){ "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"}