> ## 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.

# Quickstart

> Sign up, get an API key, and run a sandbox payment in five minutes.

This walkthrough takes you from zero to a settled sandbox transaction. You will create an account, reveal your API key, register the MCP server, create an agent and a card, declare an intent, and simulate a charge.

<Note>
  Everything in this quickstart runs in **sandbox**. Card numbers, IBANs, and webhooks are live-shaped but no real money moves.
</Note>

<Steps>
  <Step title="Sign up">
    Request a sandbox invite at [getovra.com/sign-up](https://getovra.com/sign-up). Once accepted, sign in — your sandbox organization, IBAN, default policy, and API key are auto-provisioned.

    <Tip>
      The reveal modal shows your `sk_sandbox_*` key **once**. Copy it now. You can rotate it later via **Dashboard → API Keys**.
    </Tip>

    ```bash theme={}
    export OVRA_API_KEY="sk_sandbox_..."
    ```
  </Step>

  <Step title="Connect the MCP server (optional)">
    The MCP server gives any LLM client (Claude Desktop, Cursor, Kiro, etc.) all 19 Ovra tools.

    <CodeGroup>
      ```json Claude Desktop theme={}
      {
        "mcpServers": {
          "ovra": {
            "command": "npx",
            "args": ["@ovra/mcp@latest"],
            "env": { "OVRA_API_KEY": "sk_sandbox_..." }
          }
        }
      }
      ```

      ```json Streamable HTTP (any client) theme={}
      {
        "mcpServers": {
          "ovra": {
            "type": "streamable-http",
            "url": "https://api.getovra.com/api/mcp",
            "headers": { "Authorization": "Bearer sk_sandbox_..." }
          }
        }
      }
      ```
    </CodeGroup>

    Restart your client. You should see 19 `ovra_*` tools. See [MCP setup](/mcp/setup) for advanced configuration.
  </Step>

  <Step title="Create an agent">
    An agent is a first-class entity — it owns cards, tokens, transactions, and a policy. The minimum form is `name + purpose + policyId`.

    <CodeGroup>
      ```bash curl theme={}
      curl -X POST https://api.getovra.com/agents \
        -H "Authorization: Bearer $OVRA_API_KEY" \
        -H "Content-Type: application/json" \
        -H "Idempotency-Key: $(uuidgen)" \
        -d '{
          "name": "procurement-bot",
          "policyId": "po_default_...",
          "profile": { "purpose": "Buy office supplies under EUR 100" }
        }'
      ```

      ```ts SDK theme={}
      import { Ovra } from "@ovra/sdk";
      const ovra = new Ovra({ apiKey: process.env.OVRA_API_KEY });

      const agent = await ovra.agents.create({
        name: "procurement-bot",
        policyId: "po_default_...",
        profile: { purpose: "Buy office supplies under EUR 100" },
      });
      ```

      ```text MCP theme={}
      Use ovra_agent with action "provision",
        name: "procurement-bot",
        policyId: "po_default_...",
        profile: { purpose: "Buy office supplies under EUR 100" }
      ```
    </CodeGroup>

    Returns `{ id: "ag_...", status: "active", ... }`.
  </Step>

  <Step title="Issue a card for the agent">
    Each card is bound to one agent and named uniquely within that agent. You can issue multiple cards per agent (`subscriptions`, `travel`, `one-off`).

    ```bash theme={}
    curl -X POST https://api.getovra.com/cards \
      -H "Authorization: Bearer $OVRA_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "agentId": "ag_...",
        "name": "default",
        "usage": "multi",
        "purpose": "Default card for procurement"
      }'
    ```

    Returns `{ id: "ca_...", last4: "4242", status: "active", ... }`. PAN and CVV are encrypted with AES-256-GCM at rest and never returned in plain text on this endpoint.
  </Step>

  <Step title="Declare an intent">
    No money moves without an approved intent. The policy engine and risk engine run during this call.

    ```bash theme={}
    curl -X POST https://api.getovra.com/intents \
      -H "Authorization: Bearer $OVRA_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "agentId": "ag_...",
        "cardId": "ca_...",
        "purpose": "Pack of USB-C hubs",
        "expectedAmountEuros": 29.99,
        "expectedMerchant": "amazon.de"
      }'
    ```

    If the policy auto-approves, you get back `{ status: "approved" }`. Otherwise `pending_approval` — approve from the dashboard or `POST /intents/:id/approve`.
  </Step>

  <Step title="Simulate a charge">
    In sandbox you can shortcut the merchant call:

    ```bash theme={}
    curl -X POST https://api.getovra.com/simulate/charge \
      -H "Authorization: Bearer $OVRA_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "intentId": "int_...",
        "amountEuros": 29.99,
        "merchant": "amazon.de"
      }'
    ```

    Returns a `tx_*` row with `status: "completed"`. The matching `transaction.completed` webhook fires immediately if you have a subscription registered.
  </Step>
</Steps>

## Real merchant flows

The simulate endpoint is a stand-in. For real merchant calls, pick the mode that matches the merchant:

<CardGroup cols={2}>
  <Card title="MPP" icon="lock-keyhole" href="/concepts/mpp">
    Merchant returns 402 with `WWW-Authenticate: Payment`. Use `POST /v1/mpp/pay` to mint a JWE-wrapped credential and settle in one call.
  </Card>

  <Card title="CUA" icon="browser" href="/concepts/cua">
    Merchant only has a checkout form. Mint an autofill token via `POST /v1/cua/autofill-tokens`, the harness fills the form with a tokenized DPAN.
  </Card>
</CardGroup>

## Next

<CardGroup cols={2}>
  <Card title="The six pillars" icon="layer-group" href="/concepts/pay">
    Tour Pay, Cards, Accounts, Collect, Control, and Intelligence.
  </Card>

  <Card title="Policies" icon="shield-check" href="/concepts/policies">
    Lock down what your agent can spend, where, and when.
  </Card>

  <Card title="Webhooks" icon="bell" href="/concepts/webhooks">
    Wire the \~50 event types into your own systems.
  </Card>

  <Card title="MCP tools" icon="terminal" href="/mcp/tools">
    The full action-multiplexed reference for all 19 tools.
  </Card>
</CardGroup>