# Integrating with the buckette control plane This doc is for an LLM or coding agent helping a user get set up on buckette — not for an agent that already has a tenant and just wants to use buckets day to day (that's the tenant API's own guide, `GET /docs/llm.md` on the tenant's base URL, see below). This doc covers **the control plane's own surface only**: accounts, tenants, plans, and API keys. It deliberately does not restate the tenant API's concepts (buckets, dimensions, claims, replenishment) beyond a one-line pointer — see the tenant API's own docs for that once a tenant exists. Also available at runtime: `GET /openapi.json` returns the full OpenAPI 3.0 spec for every non-admin route below (all but the few only a browser session can use: sign-out, avatars, switching accounts), machine-readable, unauthenticated (the routes it describes still need real auth — see "Authenticating as an agent" below). Fetch it to get the exact request/response shapes rather than relying on this prose. --- ## Where things are - **This API (the control plane)**: https://console-api.buckette.co Every bare path in this guide (`GET /me`, `POST /tenants`) is on this address. This guide: https://console-api.buckette.co/docs/llm.md The OpenAPI document: https://console-api.buckette.co/openapi.json - **The Console**, where a person signs in, creates a `cpk_...` key and approves a device-flow request: https://console.buckette.co/ - **The website**: https://buckette.co/ - **A tenant's API** has no single address. Each tenant is served by a buckette-core instance, and tenants can be on different ones. Its base URL is the value of the `ctrExternalUrl` field in the answer to `POST /tenants` (and of `ptiExternalUrl` in `GET /tenants`). Wherever this guide says "on the tenant's base URL", that value is meant; it is data you were given, not something to fill in from this document. That instance serves its own guide at `/docs/llm.md`. Configure that value and no other: it is meant to stay the same if the tenant is moved to another instance. `ctrDirectUrl` / `ptiDirectUrl` name the instance the tenant is on today, for information. --- ## TL;DR Two APIs, one direction of travel: ``` Control Plane (cpk_...) Tenant API (bk_...) | | |-- create tenant |-- manage budgets: buckets, |-- returns tenant endpoint ---> | claims, consume, webhooks | + admin key (bk_...) | ``` Happy path: 1. Get a `cpk_...` key — either the user hands you one from the Console, or you bootstrap it yourself via the device flow (`POST /auth/device/start`, the user approves in a browser, `POST /auth/device/token` returns the key). See "Authenticating as an agent" below. 2. `GET /me` — confirm `meAccountStatus == "active"`. 3. `GET /tenants/plan-options`, then `POST /tenants` with a `ctrPlanId` — create a tenant (Job 1 below). 4. Save `ctrAdminApiKey` (`bk_...`) immediately — it's shown once, never re-fetchable. 5. Switch base URL to the returned `ctrExternalUrl`. 6. `GET /docs/llm.md` on that URL — the tenant API's own docs take over from here for everything budget-related. Which API for what: | User wants | API | |--------------------------------------|---------------| | Create/rename a tenant | Control Plane | | Mint/revoke a `cpk_...` key | Control Plane | | File feedback | Control Plane | | Dashboards (called Monitors here) | Control Plane | | Create/manage buckets, claims, consume| Tenant | | Generate a bucket-scoped API key | Tenant | | Webhook/monitoring wiring | Tenant | Expected failure modes (not bugs — report to the user rather than retrying blindly): - `403 quota_exceeded` — the account's tenant quota is used up. - `503 no_instance_available` — no eligible instance to assign. - `wrong_key_kind` — a `bk_...` key was sent here, or a `cpk_...` key was sent to the tenant API. Invariants: - The control plane never manages budgets — all bucket/claim/consume operations happen on the tenant API, not here. - `cpk_...` and `bk_...` are not interchangeable: each is rejected by the other API (`wrong_key_kind`, not a generic auth error). - `ctrAdminApiKey` is returned exactly once, at tenant creation. It can never be re-fetched — only *replaced*, by the account owner calling `POST /tenants/:id/recover-key`, which issues a new one and deactivates only the lost one, leaving the tenant's other keys working (see "Other control-plane operations" below). Common mistakes: - ❌ Using `cpk_...` against the tenant API, or `bk_...` against the control plane. - ❌ Assuming `ctrAdminApiKey` can be fetched again later. - ❌ Calling `POST /feedback` without asking the user first. Everything below is reference detail for the four jobs an agent does here: create a tenant, help the user use buckette, help with monitoring code, and report feedback. --- ## Credential handling rules Four kinds of secret pass through this API: `cpk_...` control-plane keys, `bk_...` tenant keys (`ctrAdminApiKey`), and the device flow's `dtrKey` and `dsrDeviceCode`. Treat all four the same way. - **Never print one unnecessarily.** Not into your reasoning, not into a summary, not into a "here's what I did" recap. The user does not need to see a key to know you stored it; echoing one puts it in a transcript, a scrollback buffer, and possibly a log. - **Never write one into generated source code**, config, or a committed file. Read it from an environment variable or a secret store instead (buckette prescribes no particular variable name — pick one and say so). The only exception is a placeholder the user explicitly asked for — and a placeholder is `bk_xxxxxxxx`, not a real key with a few characters changed. - **Store one-shot credentials before doing anything else.** `dtrKey` and `ctrAdminApiKey` are each returned exactly once and are gone the moment the response is discarded. Persist first, then make the next call — not the other way round, because a failure in between loses the credential permanently. For `ctrAdminApiKey` the only remedy is `POST /tenants/:id/recover-key`, which issues a new key and deactivates only the lost one; for `dtrKey` it is another round of the device flow, which needs the human again. - **A credential the user hands you is a secret too.** It does not become quotable because it arrived in the conversation rather than from an API response. Same rules: don't echo it, don't bake it into code. - **Never put a credential in `POST /feedback`** — not in `cfrTitle`, `cfrDescription`, or `cfrExtra`. Feedback reports are read by the buckette team and are not a secure channel. If a key is genuinely relevant to a report, name *which* key it is (`"the tenant's admin key"`), not its value. The same goes for any other free-text field you fill on the user's behalf: monitor names, tenant names, bucket metadata. - **`dsrDeviceCode` is yours, `dsrUserCode` is the human's.** Show the user code, keep the device code. Getting this backwards hands the human something useless and leaks the half that authenticates you. If you think you have leaked a credential, say so plainly and tell the user how to revoke it: `DELETE /me/api-keys/:id` for a `cpk_...`, and for a `bk_...` either the tenant API's own key management or `POST /tenants/:id/revoke-keys` (which deactivates every key of the tenant). --- ## What this service is buckette itself is a resource ledger — bounded, revocable spend budgets for machine actors, with atomic multi-resource claims and signed receipts of consumption. The control plane is the layer *in front of* it: it's where an account signs up, gets a **tenant** (an isolated buckette namespace with its own root bucket and its own admin API key), and manages that tenant's lifecycle. **Using buckette starts with having a tenant** — nothing on the tenant API is reachable until `POST /tenants` has returned an admin key. --- ## Authenticating as an agent The control plane's primary auth is a browser session cookie from GitHub OAuth (or an email magic link) — not something an agent can drive. What you send instead is `Authorization: Bearer cpk_...`, the same header/scheme the tenant API uses for its own keys. It authenticates identically to the session cookie, for every route below except where noted. There are two ways to get that key. ### Option A — bootstrap it yourself (device flow) Use this when you have no credential at all and a human is around to approve. Nothing here needs a browser on *your* side. **1. Start an authorization** (no auth required): ``` POST /auth/device/start Content-Type: application/json {"dsClientLabel": "claude-code"} ``` Returns `dsrDeviceCode` (yours — keep it, never show it to the human), `dsrUserCode` (theirs, formatted `XXXX-XXXX`), `dsrVerificationUri`, `dsrVerificationUriComplete` (same page, code pre-filled), `dsrExpiresIn` (900s), and `dsrInterval`. **2. Show the human the code and the URL.** Print both — the plain URL plus the code to type, and the complete URL for a human who can just click. They will be asked to log in if they aren't (signing up in the process if they've never used buckette — this flow works for an account that does not exist yet), then shown what they're approving. **3. Long-poll for the result:** ``` POST /auth/device/token Content-Type: application/json {"dtDeviceCode": "dvc_..."} ``` This holds the connection open for up to ~20s, then returns `{"dtrStatus": "pending"}` — just call it again, until the authorization expires. (The hold was ~120s before 2026-10-06, longer than the load balancer in front of the hosted service allows, so a pending poll ended in a plain-text `504` instead of this answer. If you ever get a response that is not JSON from this route, treat it as `pending` and poll again.) Other outcomes are `"approved"` (with `dtrKey`, the `cpk_...` key, and `dtrExpiresAt`), `"denied"`, `"expired"`, and `"already_delivered"`. **`dtrKey` is shown exactly once.** Store it before doing anything else — polling again returns `already_delivered`, not the key, and there is no way to re-fetch it. If you lose it, start over. Codes are case- and dash-insensitive when the human types them. The whole authorization dies after 15 minutes. **When it goes wrong.** `POST /auth/device/start` can refuse before you get a code at all, with a 429 and one of two `errCode`s — `device_auth_capacity` (too many authorizations in flight platform-wide) or `device_auth_rate_limited` (too many started from your address recently). Both are transient: back off and retry, don't loop tightly. `POST /auth/device/token` 404s with `invalid_device_code` if the code is unrecognized — that's terminal, start a new authorization rather than retrying. Distinguish the three ways a poll ends without a key, because they want different things from you: `expired` means nobody acted in 15 minutes (start over, and show the human the new code more clearly), `denied` means a human actively refused (do **not** immediately start another one — ask first), and `already_delivered` means the key was issued and collected, so if you don't have it, it's gone. Worth saying plainly, since you are the one printing the instructions: the human is being asked to hand a program full access to their account. Show them the client label you sent as `dsClientLabel` and be honest about what you are. Don't ask a human to approve a code you didn't just generate yourself — a code someone else supplies is an attack, not a shortcut. ### Option B — a human hands you a key 1. A human logs into the Console once, normally. 2. In the Console's Account tab, they create an API key ("API keys" panel → label it, e.g. `"claude-code"` → copy the one-shot-revealed key, `cpk_...`). 3. They hand it to you, e.g. as an environment variable. ### Either way A key is scoped to the account that created it (the same account whose tenants/plans/keys it can manage) — treat it like any other credential. Keys may carry an expiry (`cpakiExpiresAt` in `GET /me/api-keys`): one you minted via the device flow defaults to 90 days, and one created through the Console expires only if the human asked for that. There are no finer-grained scopes today — a `cpk_...` can do anything its account can. **Don't confuse this with a tenant's own API key** (`bk_...`, returned as `ctrAdminApiKey` from `POST /tenants` below): a `cpk_...` key authenticates against the control plane (this API); a `bk_...` key authenticates against that tenant's own instance (`ctrBaseUrl`/`ctrExternalUrl`) and is rejected here with a distinct `wrong_key_kind` error, not the generic `invalid_api_key` a malformed/unknown key gets. --- ## Job 1 — create a tenant A tenant is always created under a plan, so pick one first: ``` GET /tenants/plan-options Authorization: Bearer cpk_... ``` `porPlans` lists the plans this account can create a tenant under. Take one whose `poiRemaining` is above 0 and use its `poiPlanId`. A new account has one: the free plan (`poiSlug: "free"`, `poiSignupCredit: true`, `poiRemaining: 1`), which is hidden from the plans for sale (`poiHidden: true`) but is the one to use for a first tenant. A plan at 0 remaining is one the account would have to buy slots of first (`POST /account/subscriptions`, a person's decision: ask before buying anything). ``` POST /tenants Authorization: Bearer cpk_... Content-Type: application/json {"ctrName": "acme-corp", "ctrPlanId": ""} ``` Returns `ctrAdminApiKey` — the tenant API's admin key for the new tenant, shown exactly once. **Save it immediately**; it can't be re-fetched. That key is what a bucket-scoped or admin-scoped client uses against the tenant's own instance from here on (`ctrExternalUrl` in the same response; see "Where things are"). - `ctrName` must be unique across this account's tenants. - `ctrPlanId` is required: without it the answer is `400 plan_required`. The plan decides which instance the tenant lands on; there is nothing else to choose. - `GET /tenants` lists what the account already has; `GET /tenants/remaining?planId=` reports how many more tenants that plan allows (the `planId` parameter is required, like the plan on `POST /tenants`). `poiRemaining` above says the same for every plan at once. - Quota exhausted (`403 quota_exceeded`) or no eligible instance (`503 no_instance_available`) are both real, expected failure modes — not bugs — report them to the user rather than retrying blindly. --- ## Job 2 — help the user actually use buckette Once a tenant exists (`ctrAdminApiKey` + `ctrExternalUrl` in hand), two shapes this help usually takes: - **Direct operation from you (the agent)** — call the tenant's own instance yourself: `POST /buckets`, `POST /buckets/:id/consume`, `POST /claims`, etc., using the admin key or a bucket-scoped key split from it. Give every bucket you create a `buckette/bucket-title` in its `cbrMetadata`/`srMetadata` (and ideally `buckette/labels`); the tenant's own `GET /docs/llm.md` has the rule. Useful for one-off setup, debugging, or an agent that *is* the spender (e.g. metering its own tool calls). - **Design and write integration code** — more common for a real application: help the user design a bucket hierarchy (one bucket per user? per task run? per API tenant of *theirs*?), which dimensions matter (tokens, requests, USD, concurrency slots), and where `POST /consume`/`POST /claims` calls belong in their existing codebase. This is the more valuable job for most users — you're generating code against *their* system, not just calling buckette yourself. For either shape, **switch to the tenant API's own docs at this point**: `GET /openapi.json` (full spec, unauthenticated) and `GET /docs/llm.md` on the tenant's base URL, which is the value of `ctrExternalUrl` in the `POST /tenants` answer (its longer-form integration guide — buckets, dimensions, modes, claims, webhooks, receipts) are both served directly by the tenant's instance, not proxied through the control plane. `GET /help` and `GET /help/:topic` on the same base URL give the same guidance as structured JSON if you'd rather introspect than read prose. --- ## Job 3 — help the user write monitoring/operational code Once buckets exist, common asks: a webhook consumer for `bucket.consumed`/ `bucket.critical_balance`/etc. events, a dashboard over `GET /buckets/:id/stats` on the tenant's base URL, alerting on a threshold webhook firing. All of this is on the tenant API, not on the control plane — same doc pointers as Job 2 apply (the tenant instance's `/docs/llm.md` has a full section on webhook wiring and async resolution patterns). When the user wants alerts in **Slack, Discord or PagerDuty**, don't build a webhook receiver: the control plane forwards a tenant's events there itself. `:id` is the tenant's `ctrId` (`ptiId` in `GET /tenants`), not `ctrTenantId`. ``` POST /tenants/:id/integrations/forwarders Authorization: Bearer cpk_... Content-Type: application/json {"cirTarget": "slack", "cirLabel": "#pipeline-alerts", "cirSecret": ""} ``` `cirTarget` is `"slack"`, `"discord"` or `"pagerduty"`; `cirSecret` is the target's credential (a Slack or Discord webhook URL, a PagerDuty Events API v2 routing key), which is checked, sealed and never returned (the answer shows `ifwSecretHint`). `cirLabel` is what the Console shows. `cirEvents` (optional) names the events to send; without it a default set of twelve is sent (low, critical, depleted, overage, recovered, shortfalls, unspent warnings; `ifwEffectiveEvents` lists them). The low and critical alerts only fire on buckets that have a threshold config (`PUT /buckets/:id/threshold-config` on the tenant's base URL). `POST /tenants/:id/integrations/forwarders/:fid/test` sends a test message, and `GET /tenants/:id/integrations` shows each forwarder's last success and last failure (`ifwLastOkAt`, `ifwLastError`). The first forwarder uses one of the tenant's webhook configs (a free tenant has one); the ones after it share it. `GET /help/forwarder-templates` covers custom message text. One part of this job is on the control plane, and it is the one to reach for first when the user asks for a dashboard: **Monitors**. A monitor is what other products call a dashboard, and it is the only name the product uses for one. It is a named page of widgets shown in the Console, each widget pinning a set of one tenant's buckets (by metadata, by subtree, by id) and showing them as a table of one dimension, a treemap, or a template you write. `POST /tenants/:id/monitors` creates one and `POST /tenants/:id/monitors/:mid/widgets` adds a widget, with the same credential as the rest of this API. `GET /help/monitors` has every route and the widget shapes; `GET /help/dashboard` answers with that same topic. Build a page of your own over the tenant API only when a monitor cannot show what the user wants. --- ## Job 4 — report feedback back to the buckette team If you hit a bug, a rough edge in these docs, or think of a feature that would help — you can report it directly through the product via `POST /feedback`, rather than the user having to file it somewhere out of band. Body: `cfrTitle` (short), `cfrDescription` (up to 256KB), `cfrCategory` (one of `"Bug"`, `"Feature"`, `"Improvement"`, `"Documentation"`, `"Complaint"`, `"Praise"`, `"Other"`), and an optional `cfrExtra`. The report is tied to the calling account and, if you're using an API key, to that specific key. Pick the category honestly rather than defensively — `"Complaint"` exists so dissatisfaction with the service has somewhere to go that isn't a mislabelled `"Bug"`. Getting it wrong isn't fatal either way: the buckette team can requalify a report later, and `friCategory` then reads back as the corrected kind. **Only send this if the user has actually agreed to share it.** This endpoint has no way to verify consent on its own — ask first, in plain language, before calling it. Don't send anything the user hasn't seen or approved. This applies to `cfrExtra` too — it's opt-in context, not something to attach by default. `cfrExtra` is an entirely optional, opaque JSON object — omit it, or send `{}`, for a plain report. Two reserved (also each individually optional) keys, matching what the Console's own "give feedback" drawer captures when a user ticks the corresponding checkbox: - `"buckette/page-info"` — a small snapshot of relevant client-side state (e.g. which tab/view was open, the current URL). Reports filed before the rename carry it as `"budgetz/page-info"`; nothing reads the key, so there is no fallback to speak of. Same reserved `buckette/` prefix as the tenant API's `buckette/bucket-title`-style bucket metadata keys, different namespace (this is a feedback payload, not a bucket's `metadata`). - `"browser/info"` — browser/OS/viewport identification (user agent, platform, viewport size). Neither key is validated or special-cased server-side — `cfrExtra` is stored and returned verbatim as `friExtra` on the resulting report. Feel free to add your own keys under a namespace that won't collide with these two if you have other structured context worth attaching (e.g. a stack trace, a request ID). `GET /feedback` lists what the calling account has already reported; `GET /feedback/:id` fetches one; `DELETE /feedback/:id` retracts one — all scoped to the account that filed them. --- ## Other control-plane operations, briefly - `GET /me` — who the caller is (`meAccountId`, `meAccountStatus`, `meIsAdmin`). `meAccountStatus` is informational: signup is open, so a new account is already `"active"`. (Accounts predating the invite system's retirement may still read `"pending"`; that is treated exactly like `"active"` — only `"revoked"` is refused.) What actually gates tenant creation is plan credit, not status — see `GET /tenants/plan-options`. - `GET /tenants/plan-options` — the plans this account can create a tenant under, each with its remaining credit, its limits and `poiPrices`: one `{ppiCurrency, ppiAmount, ppiAmountMinor, ppiExponent}` per currency the plan is sold in, a flat price per tenant per month. Show `ppiAmount` as is (it is already rendered with the currency's own decimals, "12.50" or "1250" for JPY); `ppiAmountMinor` is the exact integer. There is no currency conversion: a currency that isn't listed isn't offered. An empty list means no price has been set yet, which is not the same as free (a free plan lists an explicit `0.00`). - `GET` / `PUT /account/billing-profile` — who this account's invoices are made out to: `bpiEntityKind` (`"company"` or `"individual"`), `bpiLegalName`, an optional `bpiTaxId`, a billing address, and an optional `bpiCurrency` (the currency the customer *prefers*; what they are billed in is set per account, and a preference no plan is priced in is a warning to show, not an error). The read works for any member; the write is owner-only. An account that has never saved one reads as an empty profile with `bpiUpdatedAt: null` rather than a 404. `PUT` carries the *whole* profile as plain strings — an empty string clears that field — and nothing is required, so a half-filled profile saves. Whether it is filled in enough to buy a plan with is `bpiComplete`, with `bpiMissing` naming the columns still needed; read those rather than deciding for yourself, since it is the same flag a purchase refuses on. `bpiBillingEmail` is one of those required columns, and it is the one worth knowing about: it is where invoices, receipts and payment reminders are sent, and it is required precisely because it is the only address this service can count on having — an owner who signed up through GitHub has no email identity at all. It is a billing contact, not a login, and is expected to differ from the address anyone signs in with. Notices go to it *and* to any owner's email identity, deduped. - `GET` / `POST /account/subscriptions` and `GET /account/invoices` — buying tenant slots, and the money record of having bought them. A subscription is one plan version times a quantity of slots, at a unit price locked when it was bought; slots are what `POST /tenants` spends, so this is how an account gets more of them without an admin grant. Both reads work for any member; the purchase is owner-only. `POST` takes `psrLines` (one `{slrPlanId, slrQuantity}` per plan — buy staging and production in one purchase rather than two calls) plus optional `psrCurrency` (ISO 4217; the purchase's own currency, defaulting to the billing details' currency; an account already billed in one currency is refused, `billing_currency_locked`, if it asks for another). **A purchase does not take payment and credits no slot.** Each line becomes one subscription in status `pending_payment` and one **open** invoice, and the answer lists both. The slots arrive when that invoice is paid — through the payment processor (`POST /account/invoices/:id/checkout` below) or by an admin recording the payment — at which point the subscription becomes `active`, its first period starts at that moment (a full month from payment, not from the purchase) and its slots are credited exactly once, however many times the payment is reported. `psrPaymentReference` and `psrPaymentMetadata` are still accepted and ignored: a customer's word is not a payment. A purchase that is not paid within 24 hours (`siPendingExpiresAt`) is released: the subscription becomes `expired` and its invoice `void` (`iiVoidReason: pending_expired`). Nothing was credited, so nothing is taken back. Several pending purchases of one plan can wait at once. The owner can give one up with `POST /account/subscriptions/:id/cancel-purchase` (409 `subscription_not_pending` for anything else; a running subscription is cancelled with `cancel`). A payment that still arrives after either is recorded and flagged for a refund, with one exception: inside 24 hours of an *expiry* (not a cancellation) it brings the purchase back. An administrator returns such a payment at the payment provider; when the provider reports the refund, the payment shows it (`payRefundedMinor`, `payRefunded` on the invoice's `iiPayments`). A refund of a payment that paid an invoice is shown the same way and changes nothing else: the invoice stays `paid` and the slots stay. It refuses, before writing anything, if the account has not accepted the current terms of service and payment terms (409 `terms_not_accepted`, with the versions to accept; see "Terms" below), if the billing profile is incomplete (`billing_profile_incomplete`, with the missing fields), if no billing currency can be resolved (`billing_currency_not_set` — set `bpiCurrency` on the profile first), or if **any** line names a plan that is hidden (`plan_not_for_sale`) or has no price in that currency (`plan_not_priced_in_currency`). There is no conversion: an unpriced currency means not for sale, and one bad line fails the whole purchase rather than buying the others. A hidden plan is closed to new purchases only: a subscription bought before the plan was hidden keeps its slots, its invoices can still be paid and it renews. - `GET /account/invoices/:id/document` — one invoice as a document to file: a self-contained HTML page (`text/html`, sent as an attachment named `invoice--.html`), made to be printed or printed to PDF. Any member may read it, like the listing; another account's invoice is `invoice_not_found` (404). It shows who is billed, what for, the period, the amount, the issue and due dates and the status. A paid invoice is its own receipt: the page says "Paid" with the date and lists each payment with its reference. A void one says so. Three things to know: the reference on the page is the invoice's id (there is no invoice number); the billed party is the billing profile as it is on the day of the download, not as it was at issue, and the page says which day that is; and the page names no issuer and no tax, because neither is recorded. Where billing is fictional the page says so first. - `POST /account/invoices/:id/checkout` and `POST /account/invoices/:id/checkout/confirm` — pay an **open** invoice (a pending purchase's, or a renewal) through the payment processor. Owner-only. `checkout` answers `iciUrl`, a page the processor owns, and `iciSessionId`; send the person to the URL. Nothing is settled by opening it, and calling it twice within a quarter of an hour answers the same session. `confirm` takes a body with `ccrSessionId` and answers the invoice as it is after the control plane has asked the processor about that session: paid if the session was paid, unchanged if not (that is not an error). You do not have to call it: the processor reports the payment itself and the invoice becomes `paid` either way, so polling `GET /account/invoices` works too. Refusals: `billing_not_available` (403, billing is closed here), `payment_not_available` (409, no processor is configured: `porPaymentAvailable` on `GET /tenants/plan-options` says so in advance), `invoice_not_open` (409), `invoice_not_found` (404, also for another account's invoice), `processor_unavailable` (503: the processor did not answer or answered 5xx; a `Retry-After` header says when; this was `payment_processor_unavailable` (502) before 2026-11-06), `processor_busy` (503: the processor is rate limiting, nothing changed, try again in a moment; a `Retry-After` header says when), `processor_refused` (502: the processor refused the request, a retry as it is changes nothing), and on `confirm` `session_for_another_invoice` (409). - `GET /account/basket`, `POST /account/basket/checkout`, `POST /account/basket/checkout/:attemptId/confirm` and `POST /account/basket/checkout/:attemptId/cancel` — the **basket** is everything that currently requires payment: the open invoice of each pending purchase and each renewal that is due or overdue. `GET` is readable by any member and lists `biLines` (one per invoice: `blFlavour` `pending` | `due` | `overdue`, `blAmountMinor`, `blPayable`, `blInCheckout`, …), the total, and `biCanPay` (billing open **and** a processor configured; otherwise `biPayUnavailableReason` says `billing_not_available` or `online_payment_unavailable`). `POST …/checkout` is owner-only and takes a body with `bcrInvoiceIds`: **one** hosted checkout for the sum of the selected invoices, which is one processor session named after a *checkout attempt* (`bciAttemptId`). Send the payer to `bciUrl`. Paying settles every invoice in it, each with its own payment row, each idempotently; a replayed webhook or `confirm` changes nothing. `confirm` reads the session back (never settles from the browser arriving) and answers the attempt (`caiStatus`: `open` | `completed` | `expired` | `cancelled`); `cancel` gives the checkout up and frees its invoices (a payment the processor reports as already made wins). An invoice is never in two live checkouts. Asking again for the **same** set answers the checkout already open; a different set that overlaps it is refused, `invoice_in_checkout` (409). Payment is oldest-first within one subscription: selecting an invoice while an older open one of the same subscription is left out is refused, `older_invoice_open` (409). A checkout whose session ran out frees its invoices by itself. The per-invoice `checkout` route above is a basket of one and obeys the same rules. Other refusals: `no_invoices` (400), `invoice_not_found` (404, also for another account's invoice), `invoice_not_open` (409), `online_payment_unavailable` (409), `billing_not_available` (403), `checkout_attempt_not_found` (404), `checkout_attempt_not_open` (409), `processor_unavailable` (503), `processor_busy` (503) and `processor_refused` (502), as on the invoice routes above. **Payment mode.** Every account is `self_serve` (it pays through the processor) or `manual` (an admin records the payment when the money arrives out of band). Only an admin sets it, so the customer cannot. Both `GET /tenants/plan-options` (`porPaymentMode`, `porPayUnavailableReason`, `porPaymentInstructions`, `porPaymentNote`) and `GET /account/basket` (`biPaymentMode`, `biPaymentInstructions`, `biPaymentNote`) say which, so a client adapts: for a `manual` account `canPay` is false with the reason `payment_mode_manual`, the checkout routes answer `payment_mode_manual` (409), and the pending invoice is shown with the deployment's payment instructions (the instructions the operator configured) and the admin's per-account note. A `self_serve` account on a deployment with no processor reads `online_payment_unavailable`. The first purchase locks the account to the profile's currency. After that the owner can no longer change `bpiCurrency` (`PUT /account/billing-profile` answers `billing_currency_locked`); only an admin can, because live subscriptions are priced in the old one. - `GET /account/notices` and `POST /account/notices/:id/dismiss` — what this account has been told about its money. One notice is one thing we said, delivered twice: a row for the Console's banner and an email to the account's owners. `bniSubject`/`bniBody` are the stored text, not a re-render, so the banner and the mail say the same words even after the subscription behind them changed. The listing is newest-first and includes dismissed notices, so filter on `bniDismissedAt == null` for a banner. `bniSeverity` is `info` / `warning` / `critical`, derived from `bniKind` — show a kind you do not recognize rather than dropping it; a newer build can write one. `bniEmailedAt == null` means no mail went out, usually because no owner has an email address on file (a GitHub-only signup), so do not promise the reader one is coming — though since `bpiBillingEmail` is required for a complete profile, and completeness is what a purchase refuses on, an account that owns anything billable always has one. Dismissing is **owner-only** while reading is member-visible: a dismissal is the account's, not the reader's, and it takes the banner down for everyone including the owner who has to pay. It is idempotent and keeps the first timestamp. Notices are written by the events that cause them, never by a client: a renewal invoice being issued and a payment being recorded. Each is emitted once per event — the service enforces that, it is not a convention — so retrying either is safe and does not re-mail. **Renewal is automatic.** Each subscription renews monthly on its own anniversary, without anyone asking — a full month, never prorated. A renewal invoice is born `open` and due at the start of the period it covers. A purchase's first invoice is open too, but it waits for the purchase to expire rather than falling due, so renewals are the only invoices that can go overdue. The anniversary is anchored to when the subscription started, so one bought on the 31st bills Feb 28 and then Mar 31 rather than staying on the 28th. Renewal does not add slots — they persist while the subscription is paid for. - `POST /account/subscriptions/:id/reduce` (`{"rsrSlots": n}`) and `POST /account/subscriptions/:id/keep-slots` — drop `n` of a line's unused slots at its next renewal, and take that back while it is pending. Owner-only. The tenants on the line stay; at least one slot stays (to stop all of them, cancel). The dropped slots are held from the request on, so no tenant takes them; the line shows `siPendingQuantity` and `siPendingQuantityAt` (the start of the first period billed at it: the current period's end, or a period later when the next invoice was already issued). At that boundary the line's `siQuantity` becomes the new one and the dropped slots leave the allowance. Refusals (409): `slots_in_use`, `reduction_would_end_line`, `slot_reduction_pending`, `allowance_slots_unavailable` (another line's tenants use the free slots), `subscription_payment_overdue`. A `cancel` while one is pending takes it back first (as `keep-slots` does) and stops the line whole at its period end; resuming the cancel does not bring the drop back. - `POST /account/subscriptions/:id/cancel` and `POST /account/subscriptions/:id/resume` — stop a subscription at the end of the period already paid for, and take that back. Owner-only, like the purchase. Neither takes a body: which subscription is the whole request, and *when* is not negotiable. `cancel` moves the subscription to `cancelling` and sets `siCancelRequestedAt`; it keeps running, and keeps its slots, until `siCurrentPeriodEnd`, at which point it moves to `cancelled` and the slots leave the account's allowance. Nothing is refunded and no tenant is ever deleted by it. `resume` works right up until that happens, so cancelling is safe to offer without a confirmation dance. **Tenants on the line do not stop it.** The line runs to `siCurrentPeriodEnd` with its tenants, then ends the way a cancel at the payment provider does: each tenant on it is moved to a free slot of another of the account's subscriptions for the same plan, or, when there is none, put on hold a week after the end until a subscription covers it (a new purchase) or it is deleted. Its slots leave the allowance as the tenants leave them. No tenant is deleted, and `resume` still takes it back. A cancellation of a subscription with no tenant on it reserves its slots for the rest of the period, so those slots are no longer available for new tenants even before it ends. Expect `POST /tenants` to start refusing sooner than `siCurrentPeriodEnd` suggests. That reservation can be refused: `allowance_slots_unavailable` (409) means tenants under the account's *other* subscriptions for the same plan have taken the free slots (the allowance is one pool per (account, plan)), so something has to go before this one can give its slots back. **An overdue invoice refuses it**: while an invoice of the subscription is past its due date, `cancel` is refused with `cancel_payment_overdue` (409, `errDetails.invoiceId` names the invoice). Pay it first, as for a plan move. An invoice still open when a subscription ends is voided (`void_reason` `line_ended`). **A subscription can also be ended by someone other than its owner**: the customer unsubscribes at the payment provider, or an administrator cancels it. `siCancelSource` says who (`customer`, `processor`, `admin`). Such an ending is authoritative: it is never refused for tenants that are running, and it also stops at `siCurrentPeriodEnd` (an immediate unsubscribe ends at the end of the period already paid for, not before). `resume` is refused for it (`subscription_cancelled_externally`, 409): take it back where it was made. The owners are told at once (a billing notice of kind `subscription_cancelled_externally`, and an email), including how many tenants will then have no slot. **No tenant is ever deleted for it**, but it does not stop the overdue steps either: if an invoice of the subscription is overdue, its tenants are held, scheduled for deletion and the subscription lapses on the usual days, as if it had not been cancelled. Seven days after the period ends, tenants that no other subscription of the account for the plan has a free slot for are put on hold (a notice of kind `slots_uncovered`, with reminders a week and a day before the end), and the hold is lifted as soon as a subscription covers them or they are deleted. While a tenant is on hold, every call made with its keys is refused with `403 tenant_on_hold`, and `errDetails.reason` says why: `no_slot` here, `overdue_invoice` for an invoice past its due date, `email_unreachable` or `account_suspended`. Likewise an overdue metered invoice holds an Elastic tenant's bucket limit at what it has: the `403 quota_exceeded` on a bucket create then carries `errDetails.reason: "overdue_invoice"` (`spend_cap` or `plan` otherwise). A payment that fails at the provider is a marker only (`siPaymentFailedAt`): the invoice stays open and the usual overdue steps run from its due date. - `PATCH /tenants/:id` — rename a tenant's display title. Nothing else about a tenant is mutable after creation today. - `POST /tenants/:id/first-key` — **owner-only, once.** A tenant created while no instance had room is queued and provisioned later, so `POST /tenants` returned no `ctrAdminApiKey` for it. Once it is ready, `GET /tenants` lists it with `ptiFirstKeyPending: true`; this call mints its first non-expiring admin key, returned once in the same shape as the create response (`ctrAdminApiKey`), and clears the flag. A second call answers 409 `first_key_not_pending`. Store the key before doing anything else, like any one-shot credential. It does not invalidate any other key. - `POST /tenants/:id/recover-key` — mint a replacement `bk_...` admin key for a tenant whose key was lost. **Owner-only.** It deactivates only the admin key buckette holds for the tenant (the one handed out at creation, or the last recovered one: the lost key) and leaves every other key, including bucket-scoped keys handed to other clients, working. The new key is returned once, as `rtkrApiKey`. `GET /tenants/key-recoveries` lists past recoveries and revocations (they are audited). - `POST /tenants/:id/revoke-keys` — for when keys are believed compromised. **Owner-only, and destructive**: it deactivates *every* existing key on the tenant, including bucket-scoped keys handed to other clients, so anything still using an old key starts failing immediately, and returns a fresh admin key (same response as `recover-key`) so the tenant is never left without one. Ask the user before calling it — "I lost the key" and "my keys leaked" are different requests; only the first is `recover-key`. - `POST` / `GET` / `DELETE /me/api-keys` — manage control-plane API keys themselves (what this doc told you to use in "Authenticating as an agent"). An agent can mint its own additional keys using one it already has. For the *first* key, see the device flow in "Authenticating as an agent" — you can bootstrap it yourself, but a human still has to approve it in a browser (an API key is a credential; something has to vouch for the first one). - `POST /auth/device/start` / `POST /auth/device/token` — the device flow itself. Unauthenticated, for obvious reasons. - `POST` / `GET` / `DELETE /feedback` — file, list, and retract feedback reports. See "Job 4" above — get the user's consent before filing one. ## Terms `GET /legal` (no credential) returns the terms of service and the payment terms: `ldiSlug` (`terms`, `payment-terms`), `ldiTitle`, `ldiVersion`, `ldiEffectiveDate`, `ldiWebsiteUrl` and the text in CommonMark (`ldiMarkdown`). `GET /me`'s `meTerms` says which versions are current (`tsCurrent`), what the account last accepted (`tsAccepted`: versions, date, who, and `taiSource`) and whether that is the current pair (`tsCurrentAccepted`). Buying slots (`POST /account/subscriptions`) and switching a tenant onto the Elastic plan are refused with 409 `terms_not_accepted` until it is. An owner accepts with `POST /account/terms/accept` and `{"atrTermsVersion", "atrPaymentTermsVersion", "atrSource"}` (`source` is `onboarding` or `account`), naming the versions they were shown: anything but the current pair is 409 `terms_version_stale`. It answers the whole `Me`. Acceptance is a person's decision for the account: an agent should send its human to the Console (Account > Settings) rather than accept on their behalf. An administrator impersonating the account cannot accept.