---
title: "Mint a tenant-bound embed token"
method: POST
path: "/api/v1/embed-tokens"
tags: ["embed"]
---

# Mint a tenant-bound embed token

`POST /api/v1/embed-tokens`

## Request

- Base URL: `https://worthune.com`
- URL: `https://worthune.com/api/v1/embed-tokens`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Short-lived, household-scoped, HMAC-signed token that lets the tenant's own site frame a real household through /embed/household/*. Growth plan; requires a configured domainAllowlist.

## Request body

- object
  - `householdId` integer, required
  - `widget` 'overview' | 'projection' | 'monte-carlo' | 'decisions' | 'lodestar-inbox' | 'lodestar-ledger' | 'lodestar-mandate-setup': Binds the token to one widget. Household widgets are served at /embed/household/{widget}; "lodestar-inbox", "lodestar-ledger" and "lodestar-mandate-setup" at /embed/lodestar/{inbox|ledger|mandate-setup}. Omitted: any widget, and embedUrl names "overview".
  - `expiresInSeconds` integer

## Response `200`

The token and a ready-to-frame URL.

- object
  - `ok` unknown, required
  - `token` string, required
  - `expiresAt` string, date-time, required
  - `embedUrl` string, uri, required

## Other responses

- `400`: Malformed JSON, missing householdId, unknown widget, or expiresInSeconds out of range.
- `401`: No key presented (Authorization: Bearer wk_… or X-Api-Key).
- `402`: Unrecognized or revoked API key.
- `403`: Role below owner, or the plan is not Growth.
- `404`: Household not found or archived.
- `409`: No domainAllowlist configured on /api/v1/tenant-config yet.
- `429`: Hourly per-org stateful quota, a per-route durable limit, or the 120 requests/minute per-IP burst backstop.
- `503`: Billing is not configured on this deployment; household resources are disabled rather than served without tenancy (production fail-closed).

---

[API](https://skmtc.dev/worthune/apis/worthune-api.md) · [All operations](https://skmtc.dev/worthune/apis/worthune-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worthune/apis/worthune-api/revisions/9f2241072555?raw)