Debug bundles
Capture a redacted diagnostic copy of a sign-in, share it for 15 minutes, and know what is never captured.
A debug bundle is a redacted diagnostic copy of one sign-in. Use it when a sign-in fails and you, the customer’s IT admin or OhAuthCat support need to see which checks ran and what the IdP sent, without passing raw SAML around.
Developers use the management API with a current human environment:write session (dashboard or CLI). Organization IT admins use the same actions from the hosted portal, scoped to their own organization’s connections.
Capture window
Section titled “Capture window”Optional SAML diagnostics come from a short capture window that you open on one connection:
- Open it with POST
/, read it with GET and end it early with DELETE.v1/ connections/ {conn}/ debug_capture - A window lasts at most one hour and admits at most 20 captures. Slots do not refill.
- The response reports
capturedandremainingout of 20 and the window’sexpires_at. Read it as “captured N of 20”. - Counts are completed, authenticated captures, not every attempt.
Capture happens in the region that served the sign-in. Sign-ins served by another region, or during a diagnostic outage, are not captured. Capture never changes whether a sign-in succeeds. Opening, closing and each capture are audited without the captured values.
Create and read a bundle
Section titled “Create and read a bundle”Create a bundle from a sign-in ID with POST /v1/debug_bundles and a body of { "sign_in": "<id>. List ready bundles, newest first, with GET /v1/debug_bundles (optionally ?connection=); expired and purged bundles are not listed. Read one bundle’s metadata with GET / and the redacted document with GET /. The setup portal offers the same bundles to the organization’s IT admin.
A bundle holds the recorded validator checks, the sign-in timeline and the connection’s current IdP metadata. diagnostic_available says whether captured SAML diagnostics exist. Older sign-ins, and OIDC sign-ins without recorded checks, say plainly that evidence is unavailable rather than guessing.
Redaction is structural: values, identities and recognizable credentials are masked; attribute names and types stay; certificates become fingerprints. The result is a diagnostic copy and is not a valid signed SAML message. Attribute preview data and OIDC tokens never enter a bundle.
Share links
Section titled “Share links”POST / mints a link that anyone holding it can open, for example a support engineer. Each link:
- expires after 15 minutes, or sooner if the bundle itself expires first;
- is stored only as a hash and opened through an audited fixed path;
- is served with
no-store,noindexandno-referrer.
To end sharing early, DELETE / revokes every live link of the bundle at once; links have no ID of their own. A revoked link answers 404, the bundle itself stays readable, and the revocation is audited even when no link was live.
Treat a share link like a password. Send it over a private channel.
When bundles are unavailable
Section titled “When bundles are unavailable”Bundles are kept in the deployment’s export object store. A deployment without one answers 503 debug_bundles_unavailable, from both the management API and the portal. Creating a bundle answers it once the sign-in is found and authorized, and writes nothing; reading a bundle answers the same code. The error is not retryable: retrying will not help until the deployment configures the store.
Retention
Section titled “Retention”The captured source expires on a fixed schedule from the moment of capture. Creating a bundle or sharing it does not extend it.
| Plan | Maximum retention |
|---|---|
| Free and Pro | 7 days |
| Business | 30 days |
| Enterprise | Configured, up to 90 days (30 days by default) |
Coming later
Section titled “Coming later”- Listing bundles and revoking share links from the hosted portal. Today IT admins can capture, create, read and share; listing and revocation are developer API routes only.
See sign-in history for finding the sign-in ID and the management reference for exact shapes.