# Embed tokens (/docs/api-reference/embed)

## Mint an embed token [#mint-an-embed-token]

<EndpointHeader method="POST" path="/api/v5/merchant/embed-token" />

Scope: **`commerce.embed`**

Mints a short-lived token that lets **one registered website** frame **one checkout** (or your Swop cart). Register websites first in the Swop app under **Dashboard → Developer**; a key can't register them. Full guide: [Framed checkout](/docs/payments/framed-checkout).

### Body [#body]

| Field | Type | Required | Notes |
|---|---|---|---|
| `scope` | string | No | `"intent"` (default) or `"store"` |
| `intentId` | string | When `scope` is `intent` | A checkout you created with [`POST /checkout-intents`](/docs/api-reference/checkout-intents) |
| `storeHandle` | string | When `scope` is `store` | Your Swop handle |
| `origin` | string | Yes | The registered origin that will frame it, e.g. `https://shop.acme.com`. `https` only (`http://localhost` allowed), no path, query, fragment or wildcard. |

```bash tab="curl"
curl -X POST https://apps.apiswop.co/api/v5/merchant/embed-token \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "intent", "intentId": "co_7Hk2mPq9xR4s", "origin": "https://shop.acme.com" }'
```

```js tab="Node"
const res = await fetch('https://apps.apiswop.co/api/v5/merchant/embed-token', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ scope: 'intent', intentId: 'co_7Hk2mPq9xR4s', origin: 'https://shop.acme.com' }),
});
const { data } = await res.json();
```

```python tab="Python"
import os, requests

r = requests.post(
    "https://apps.apiswop.co/api/v5/merchant/embed-token",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
    json={"scope": "intent", "intentId": "co_7Hk2mPq9xR4s", "origin": "https://shop.acme.com"},
)
data = r.json()["data"]
```

### Response [#response]

```json
{
  "state": "success",
  "data": {
    "token": "eyJzYyI6ImludGVudCIs….Q2x…",
    "scope": "intent",
    "origin": "https://shop.acme.com",
    "expiresIn": 600
  }
}
```

| Field | Meaning |
|---|---|
| `token` | Append as `?embed_token=` to the framed URL |
| `scope` | `intent` or `store` |
| `origin` | The normalised origin the token is bound to |
| `expiresIn` | Seconds: 600 for `intent`, 300 for `store` |

### Errors [#errors]

| Status | When |
|---|---|
| `400` | `scope` isn't `intent` or `store`; invalid origin; missing `intentId`/`storeHandle`; embedded checkout not configured on Swop's side |
| `403` | The origin isn't registered (`https://shop.acme.com is not a registered embed origin for this merchant. Add it in the Swop app first.`), or the key lacks `commerce.embed` |

## Where to frame [#where-to-frame]

| `scope` | URL |
|---|---|
| `intent` | `https://www.swopme.app/checkout/{intentId}?embed_token=TOKEN` (or the checkout's `checkoutUrl`) |
| `store` | `https://www.swopme.app/sp/{handle}/cart?embed_token=TOKEN` |
