# Claimable sandboxes

A claimable sandbox is a temporary test environment created without an account. The quickest way to get one is [`ohauthcat init`](#from-the-cli). This page does not announce a hosted try-it button.

<a id="from-the-cli"></a>

## From the CLI

Run `ohauthcat init` with no saved profile and no `OHAUTHCAT_API_KEY`. It asks "No OhAuthCat account found. Create a free test sandbox? It opens your browser." Answer yes, or pass `--sandbox` to skip the question. In a non-interactive shell, `init` without `--sandbox` stops before it makes any request.

1. The CLI starts a handoff with `POST /v1/sandboxes/handoffs`, sending only the S256 challenge of a secret it keeps (RFC 7636 PKCE). It opens the returned browser page, or prints its link when no browser opens or you pass `--no-open`.
2. The browser page runs a bot check and creates the sandbox. The keys are sealed into the handoff and never shown on the page; it tells you to return to your terminal.
3. The CLI polls `POST /v1/sandboxes/handoffs/token` with its secret and receives the keys exactly once. Only the CLI that started the handoff can redeem it.
4. The CLI saves the secret key in your OS keychain as the selected profile `sandbox.<environment>` and never prints a key. It then prints "Sandbox ready. Claim it into an account within 7 days:" followed by the claim link, and `init` continues with that profile.

The claim link is a bearer capability: anyone who has it can claim the sandbox into their account. Open it while signed in to the dashboard to [claim the sandbox](#claim-once) before it [expires after 7 days](#expiry-deletes-the-sandbox).

Handoff creation allows 5 per IP address per rolling hour and 20 per day, with IPv6 counted by /64 prefix. Press Ctrl-C to stop waiting.

<a id="setup-link-expired"></a>

### "This setup link has expired"

The browser page or the CLI shows "This setup link has expired. Run ohauthcat init again." when the handoff timed out, was already used, or was invalidated after wrong secrets. The API answers [`sandbox_handoff_expired`](/errors/sandbox_handoff_expired/). No sandbox keys reach you from that handoff. Run `ohauthcat init` again to get a new link, and open the link the new run prints rather than an old browser tab.

## Create from the API

`POST /v1/sandboxes` is public and requires `turnstile_token`, a Cloudflare Turnstile proof. The token must come from a widget rendered with `data-action="sandbox_create"` on one of the operator's configured hostnames. Dashboard sign-up uses the action `sign_up`, and a token solved for one flow is refused by the other. It returns `environment`, `secret_key`, `publishable_key`, `claim_url` and `expires_at`. Keys use `sk_test_` and `pk_test_`. Treat the claim URL as a bearer capability: keep it private and never log it or its token. The server stores a peppered hash, not the raw claim token.

Creation allows 3 sandboxes per IP per rolling hour and 10 per rolling day. IPv6 addresses are counted by /64 prefix. The global daily allowance is operator-configurable, defaulting to 2,000. Exceeding an allowance returns HTTP 429 [`rate_limited`](/errors/rate_limited/) with `Retry-After`; do not rotate addresses to evade it.

An unclaimed sandbox is test mode only. Its server-enforced caps are 3 organizations, 3 connections, 1 directory and 100 directory users. It cannot create live keys or production environments, use custom domains or log streaming, send customer email, or deliver outbound webhooks to arbitrary destinations. The authenticated [developer relay](/events/dev-relay/) is the outbound-event exception. The broader sandbox test-IdP behavior and hosted availability are described separately in [testing guidance](/get-started/sandbox-and-test-idp/).

## Claim once

Claiming happens in the dashboard: open the claim link while signed in with a verified email. Current account membership and authorization are checked; possessing the token alone is insufficient.

A successful transaction transfers the sandbox project to the authorized user's account, changes its plan to Free, consumes the claim token and records an audit event. Existing stored keys remain valid; their original expiry still applies.

## Rotate the keys issued before the claim

The keys returned at creation went to an anonymous caller, and anyone who saw them can still use them after the claim. After the claim, the dashboard lists those keys (never their secrets), newest first. Claiming itself never rotates or revokes them. For each ID:

1. Roll it on the dashboard's **API keys** page, and put the new secret in your server's environment.
2. Revoke the old key on the same page.

After both steps, no key shown before the claim keeps working. Claiming does not turn the test environment into a production environment. Free-plan resource limits replace the unclaimed caps.

A repeated claim or a claim after expiry returns HTTP 404 without revealing which condition occurred. Keep using the same project only after a successful claim; never assume that a timed-out request failed before consuming the token.

## Expiry deletes the sandbox

Unclaimed sandboxes expire after 7 days, counted from creation. Expired authority is refused by management, sign-in/profile and SCIM paths. No reminder email is sent.

After the deadline, OhAuthCat deletes the sandbox. Its keys are revoked first and the environment stops being served, then its organizations, connections, directories, events, uploads and stored files are deleted, followed by a 24-hour sweep that removes anything written while the deletion was starting. Nothing is recoverable afterwards: claim a sandbox you want to keep before its seventh day. A claimed sandbox is never deleted this way. Audit records are kept until their normal retention ends. Unclaimed activity is excluded from customer usage attribution while security and operational evidence is preserved.
