> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getovra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> What's simulated, what's real, and how to know which API mode you're in.

Sandbox is the only mode that exists in v1.2. Every Ovra customer is auto-provisioned into sandbox on sign-up — no KYC, no SEPA, no real money. Live mode (real EMI onboarding, real KYC, real settlement) is on the v1.3+ roadmap, post-raise.

<Warning>
  Do not build production traffic against sandbox. The IBAN sequence is deterministic, balances are simulated, and webhook events fire instantly without real card-network round-trips. Sandbox is for development and demos only.
</Warning>

## API key prefixes

| Prefix         | Mode                              | Source                      |
| -------------- | --------------------------------- | --------------------------- |
| `sk_sandbox_*` | Sandbox                           | Auto-provisioned on sign-up |
| `sk_test_*`    | Sandbox                           | Manual via `POST /keys`     |
| `sk_live_*`    | Live                              | v1.3+ only                  |
| `at_*`         | Sandbox or live (mirrors creator) | Per-agent token             |
| `at_dlg_*`     | Sandbox or live (mirrors creator) | Delegation-redeemed token   |

Every response carries `X-Ovra-Mode: test` or `X-Ovra-Mode: live` derived from the token prefix. Inspect this header in CI to refuse to run live tests against sandbox keys (and vice versa).

## What's real in sandbox

* Hono API, every endpoint, every error code
* Policy engine + risk engine evaluations (real signals, real decisions)
* Webhook delivery, signing, retries
* Audit log writes (append-only, PG RULES enforced)
* Idempotency-key behavior
* Rate limits
* Card encryption (AES-256-GCM at rest)
* Multi-card per agent, freeze/rotate/close

## What's simulated in sandbox

* IBAN issuance (deterministic `DE89370400440{N}`)
* Wallet balance funding (`POST /fund` with `simulate: true`)
* Card authorization + settlement (no real card network)
* SEPA-out (no real SEPA provider)
* SEPA-in (no inbound reconciliation)
* KYC (`kycStatus: sandbox` skips IDNOW)

## Test cards

For card-rail sandbox flows you can use:

| Card               | Number                | Behavior             |
| ------------------ | --------------------- | -------------------- |
| Success            | `4242 4242 4242 4242` | Approves             |
| Decline            | `4000 0000 0000 0002` | Generic decline      |
| Insufficient funds | `4000 0000 0000 9995` | Insufficient balance |

Default test expiry `12/28`, CVV `123`.

## Auto-provisioning flow

<Steps>
  <Step title="Clerk webhook fires">
    `organization.created` arrives.
  </Step>

  <Step title="Atomic provisioning">
    A single transaction:

    * Pulls next index from `sandbox_test_counter`
    * Creates `customers` row with `kycStatus: sandbox`, `companyName: "Sandbox Test #N"`
    * Provisions deterministic sandbox identity (`iban DE89370400440{N}`)
    * Hashes and stores `sk_sandbox_*` key
    * Creates billing account (Free tier)
    * Writes default policy
    * Marks `provisioning_jobs` `provisioned`
  </Step>

  <Step title="Welcome page polls">
    `/dashboard/welcome` polls every 250ms (max 2s) for the provisioning job.
  </Step>

  <Step title="Reveal modal">
    Once provisioned, the dashboard shows your `sk_sandbox_*` key plus a pre-filled `mcp.json` snippet. **One-shot reveal — copy it now.**
  </Step>
</Steps>

## Going live (v1.3+ — not yet available)

When live mode opens, the path will be:

1. Complete KYC via **Dashboard → Go Live** (IDNOW or partner-native).
2. `kycStatus` flips `pending → submitted → verified`.
3. Real EMI onboarding via the issuer adapter's onboarding hook.
4. Real funding IBAN issued.
5. Create `sk_live_*` keys.

## Sandbox indicator

The dashboard shows a small **Sandbox** pill in the sidebar at all times. There is intentionally no page-wide banner — the pill is the canonical placement.

## Next

<CardGroup cols={2}>
  <Card title="Funding" icon="piggy-bank" href="/concepts/funding">
    How to add simulated balance.
  </Card>

  <Card title="Compliance" icon="scale-balanced" href="/concepts/compliance">
    Why we won't unlock live until post-raise.
  </Card>

  <Card title="Quickstart" icon="play" href="/quickstart">
    Five-minute sandbox walk-through.
  </Card>
</CardGroup>