# Debug bundles

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

Optional SAML diagnostics come from a short capture window that you open on one connection:

- Open it with POST `/v1/connections/{conn}/debug_capture`, read it with GET and end it early with DELETE.
- A window lasts at most one hour and admits at most 20 captures. Slots do not refill.
- The response reports `captured` and `remaining` out of 20 and the window's `expires_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

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 `/v1/debug_bundles/{bundle}` and the redacted document with GET `/v1/debug_bundles/{bundle}/content`. 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

POST `/v1/debug_bundles/{bundle}/share_links` 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`, `noindex` and `no-referrer`.

To end sharing early, DELETE `/v1/debug_bundles/{bundle}/share_links` 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

Bundles are kept in the deployment's export object store. A deployment without one answers 503 [`debug_bundles_unavailable`](/errors/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

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

- 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](/sso/sign-in-history/) for finding the sign-in ID and the [management reference](/reference/api/management/) for exact shapes.
