---
title: "Mint Billing Handoff"
method: POST
path: "/api/v1/billing/handoff"
tags: ["billing-handoff"]
---

# Mint Billing Handoff

`POST /api/v1/billing/handoff`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/billing/handoff`
- Auth: none declared

Mint an owner-scoped, short-lived billing handoff token.

Owner-only + session-only. Returns 403 for admin/member/API-key callers and
503 when the signing key is unconfigured (fail-closed).

The token's ``iss`` / ``aud`` claims (``billing_handoff_issuer`` /
``billing_handoff_audience``) are FROZEN cross-repo JWT contract values
verified by the external billing service — they are NOT repo or service
names. ``billing`` is the function; the external service provides it.
Changing either claim is a coordinated breaking change (the verifier must
change in lockstep), never a local rename.

## Headers

- `authorization` string, nullable

## Request body

- BillingHandoffRequest: Request to mint a handoff token for one owned workspace.
  - `workspace_id` string, uuid, required: The workspace to start a billing session for. The caller MUST be its owner — the owner check binds to this value, not the session's current workspace.

## Response `200`

Successful Response

- BillingHandoffResponse: The minted handoff token and the metadata the billing host needs.
  - `token` unknown, required
  - `token_type` unknown
  - `kid` unknown, required
  - `jti` unknown, required
  - `expires_at` unknown, required
  - `url` unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/aa9df1a21db9?raw)