API keys

A business manages its own API keys on the dashboard, at Keys (/dashboard/business/keys). There is one lifecycle — create, rotate, revoke, list metadata — parameterized by a single field, scope:

type BusinessKeyScope = "model" | "reporting";

• model — bound to exactly one registered application (its application_id is required at creation). Use it to authenticate the application's own server-side calls — though note that a model-scope key is a business-identity credential, distinct from the personal session that identifies which user a standard or premium call is on behalf of; see Personal login.
• reporting — not bound to any single application. Use it to authenticate business.info() reads across every application the business owns.

Creating a key

Creation takes the scope (and, for model scope, the target application_id) and an idempotency key, and returns the raw secret value exactly once, in the creation response body itself:

const created = await createBusinessKey(
  { scope: "model", application_id: "app_123" },
  idempotencyKey
);
// created carries the raw key value — store it now. It cannot be read back.

The raw key is never shown again after this response. There is no "reveal" endpoint and no way to recover a lost key short of rotating it. Copy it into your own secret storage immediately; every later read of this key (the list view, the application detail view) shows only safe metadata — id, name, prefix, scope, environment, status, creation time, optional expiry, optional last-used time — never the value itself.

Rotating a key

Rotation replaces a key's secret value while keeping its identity, scope, and application binding. It also takes an idempotency key, and — like creation — returns the new raw value exactly once, in the rotation response only:

const rotated = await rotateBusinessKey(keyId, idempotencyKey);
// rotated carries the new raw key value — the old value stops working.

Rotate a key you suspect was exposed rather than deleting and recreating it, if you want to preserve its identity and metadata history.

Revoking a key

Revocation is a plain delete, and — unlike creation and rotation — takes no idempotency key, because deleting an already-deleted key is safe by construction: there is nothing to deduplicate.

await deleteBusinessKey(keyId);

Never display a raw key after its one response

Every code path in your own application that handles a createBusinessKey or rotateBusinessKey result should treat the raw value as write-once, read-never: render it to the operator exactly once, in the same response cycle it was returned, and never persist it anywhere your own UI could read it back from later (a database column your dashboard queries, a log line, an analytics event). If it is lost, rotate the key — there is no recovery path that displays the old value again.