# Overview

<div className="rw-hero">
  <p className="rw-kicker">RoamWorks Partner API v1</p>
  <h1>Local, regional and global eSIM infrastructure for partners and their agents.</h1>
  <p className="rw-lede">
    RoamWorks is a wholesale eSIM platform. Approved partners discover local, regional and global
    offers, bind a 15-minute quote, pay from a prepaid USD, EUR or GBP wallet, and redeem
    purchased eSIMs through a controlled server-to-server API.
  </p>
  <div className="rw-actions">
    <a className="rw-button" href="/docs/quickstart">Start the quickstart</a>
    <a className="rw-button rw-button-secondary" href="/docs/api.md">Read the raw API Markdown</a>
    <a className="rw-button rw-button-secondary" href="/docs/agent-prompt.md">Copy the agent prompt</a>
  </div>
</div>

<div className="rw-pills">
  <span className="rw-pill rw-pill-accent">Partner-only</span>
  <span className="rw-pill">HMAC-SHA256</span>
  <span className="rw-pill">USD / EUR / GBP</span>
  <span className="rw-pill">OpenAPI 3.1</span>
  <span className="rw-pill">Server-to-server</span>
</div>

The API is built for approved resellers and their authorised agents. It is not a public
shopping API. Every commerce call is signed, scoped, rate limited and audited, and the wallet
is the only payment source for orders. The wallet is funded through Stripe Checkout; the API
never receives card details.

## What you can build

<div className="rw-grid">
  <div className="rw-card">
    <h3>Catalogue and quotes</h3>
    <p>List eligible local eSIM offers, then bind offer, quantity and currency to a 15-minute quote, or use one-call ordering.</p>
  </div>
  <div className="rw-card">
    <h3>Wallet-funded orders</h3>
    <p>Create one atomic purchase with a stable reference and idempotency key. No order and no debit if stock, price or funds fail.</p>
  </div>
  <div className="rw-card">
    <h3>Controlled redemption</h3>
    <p>Redeem up to 20 eSIMs per idempotent batch and deliver LPA text or QR SVG into an entitled channel.</p>
  </div>
  <div className="rw-card">
    <h3>Delegated agents</h3>
    <p>Issue scoped agent credentials with budgets, expiry, IP allowlists and per-order/daily/rolling caps. Budget enforcement is live; human approval above a threshold is planned.</p>
  </div>
</div>

## Contract status

The docs mark every endpoint and feature with one of three states. Read these labels literally.

| State | Meaning |
| --- | --- |
| **Current** | In the published v1 OpenAPI contract and implemented on the v1 API. Safe to build against for sandbox integration. |
| **Preview** | Implemented in the v1 service but not yet in the published OpenAPI contract. The path, scope or response may change. Use only behind a feature flag and a human owner. |
| **Planned** | Designed but not available. Do not call it. Do not assume a launch date. |

The generated [API reference](/api) is built from the published OpenAPI document at
[OpenAPI JSON](/openapi/v1.json). The compact, complete reference is
<a href="/docs/api.md">raw API Markdown</a>, and the paste-ready agent system prompt is
<a href="/docs/agent-prompt.md">agent-prompt.md</a>. The OpenAPI document covers the current
paths; the Markdown reference carries the operational detail and recovery rules.

:::caution[Contract assumptions]
The published OpenAPI document is the canonical machine contract. Agent management, usage,
activity, one-call ordering and 15-minute quotes are in the schema. Human approval above a
threshold and the MCP server are **Planned**. If this page and the Markdown reference disagree, the
<a href="/docs/api.md">raw API Markdown</a> wins, because it records the rollout state explicitly.
:::

## The commerce path

```text
GET  /v1/capabilities          confirm flags
GET  /v1/catalog?currency=USD  choose an available offer
POST /v1/quotes                bind offer, quantity, currency, 15-minute expiry
POST /v1/orders (one-call)     buy items directly with an expected total
POST /v1/orders                pay from the wallet with a stable reference and unique idempotency key
GET  /v1/orders/{purchaseId}   inspect the purchase and child orders
POST /v1/orders/{id}/redeem    reveal up to 20 eSIMs into an entitled channel
```

A catalogue read does not reserve stock. A quote is not a payment. An order is the first
state-changing step, and redemption is the first step that reveals bearer credentials.

## What is live, what is not

| Capability | v1 status |
| --- | --- |
| Local eSIM catalogue | Current |
| Regional and global catalogue | Current |
| Quotes (15 minutes, 200 lines / 5,000 units) | Current |
| One-call wallet order | Current |
| Quote-based wallet order | Current |
| Multi-currency wallet | Current |
| Redemption | Current (POST); GET is planned |
| Partner webhooks | Current (configured in the dashboard) |
| Stripe Checkout wallet funding | Current when configured; returns 501 while disabled |
| Direct card purchase | Not available |
| Partial fulfilment | Processing and failed statuses are current; partially_fulfilled is planned |
| Usage, progress and traffic reset | Not available |
| Physical SIM | Early access only, no ordering endpoint |
| Agent manifest | Current |
| Agent identities and agent keys | Current |
| Quote lookup (`GET /v1/quotes?id=`) | Preview |
| Agent budget enforcement | Current |
| Human approval workflow | Planned |
| MCP server | Planned, not live |

:::note[No upstream identifiers]
Catalogue and order responses deliberately omit upstream store identifiers, product codes, cost
and margin data. Do not attempt to infer or publish them. This documentation contains no
credentials, customer records or private commercial terms.
:::

## Security posture

- TLS 1.2 or newer, HSTS and a WAF in front of the API.
- HMAC-SHA256 signatures with a five-minute timestamp window and nonce replay protection.
- Scoped keys, optional per-key IP allowlists, expiry and immediate revocation.
- LPA strings and QR codes are bearer secrets. Never log, cache, email or display them outside the
  entitled partner system.
- No secrets or LPA data in request logs. Redemption reveals are audited.
- Report a suspected credential exposure to [security@roamworks.io](mailto:security@roamworks.io).

## Start here

1. Read [Environments](/docs/environments) and [Quickstart](/docs/quickstart) to create a sandbox key and complete a signed request.
2. Read [Authentication](/docs/authentication) before writing your signing helper.
3. Read [Limits and quotas](/docs/limits-and-quotas) and [Errors](/docs/errors) before retry logic.
4. If an autonomous agent will call the API, read [Agent identities](/docs/agent-identities),
   [Agent payment](/docs/agent-payment), [Approval flow](/docs/approval-flow) and
   [Prompt](/docs/prompt).

Partner support: [partners@roamworks.io](mailto:partners@roamworks.io). Security:
[security@roamworks.io](mailto:security@roamworks.io). Dashboard:
[roamworks.io/partners](https://partners.roamworks.io/partners).