---
title: "Update My Tokens"
method: PATCH
path: "/users/me/tokens"
tags: ["users"]
---

# Update My Tokens

`PATCH /users/me/tokens`

## Request

- Base URL: `https://app.zeno-works.ch` (the document declares no server; this is the origin it was published from)
- URL: `https://app.zeno-works.ch/users/me/tokens`
- Auth: none declared

Switch the caller's own extra tokens on or off (jwt). **The switch is rule 5's.**

Writing only `use_extra_tokens`: balances are written by charges, and an editable
magnitude would break the identity every account holds against its `token_charge`
rows.

**Switching it on releases work held on the budgets**, so buying and then enabling
drains the queue in the same minute rather than a day later — `release_quota_holds`
decides whether the payer is actually funded, so switching it *off* releases nothing.

**One transaction**, holding the account row from the write through the release. The
earlier split — write, commit, then scan in a second transaction "so the file scan
never runs under the account row's lock" — bought a shorter lock with two defects: a
failure in the second half answered 500 with the switch already committed, and a
concurrent charge could place a hold in the gap that the release then never saw
(the release decides on a balance read, so a hold written after that read stays held
until the next funding event). The lock is the payer's own row and the scan is bounded
by their own held files, so the cost of holding it is a charge to this same payer
waiting; the cost of not holding it is a document held for a day.

`PayerScopedDep` for the reason re-pointing a payer needs its own elevation: a payer is
very often not a member of the companies they pay for, so releasing their held
documents is refused under their own principal by the tenant scope. The elevation
grants no authorization — the row written is the caller's own account, keyed on their
user id — and it refuses a support session and a company-scoped key on the way in.

## Headers

- `authorization` string, nullable

## Cookies

- `access_token` string, nullable

## Request body

- MeTokensUpdate: The billing user's own switch. **The only field the customer may write** — every balance is written by a charge, so nothing else belongs here.
  - `use_extra_tokens` boolean, required

## Response `200`

Successful Response

- MeTokensOut: The billing user's own token budgets — the one surface that may show them numbers. It is the payer's own account, so there is nothing to withhold: every figure here is about their own spending, not a sibling tenant's. `available` is **signed**, so a buyer can see what a purchase has to exceed before it unblocks anything (tokens spent past zero by calls already in flight are carried as `unfunded_tokens`).
  - `has_account` boolean, required
  - `onboarding_allowance` integer, required
  - `onboarding_consumed` integer, required
  - `onboarding_left` integer, required
  - `monthly_limit` integer, required
  - `monthly_used` integer, required
  - `monthly_left` integer, required
  - `resets_at` string, date-time, nullable
  - `extra_left` integer, required
  - `use_extra_tokens` boolean, required
  - `unfunded_tokens` integer, required
  - `available` integer, required
  - `enforced` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zeno-works/apis/zeno-api.md) · [All operations](https://skmtc.dev/zeno-works/apis/zeno-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zeno-works/apis/zeno-api/revisions/1eb93dde146c?raw)