Organization and keys

Three things in the platform are easy to confuse: the organization, the keys it mints, and the projects a key can be assigned to.

• Your organization is the account: the thing you sign up, invite people into, and cap. Keys, provider keys, caps, receipts and members all belong to exactly one organization, and each member holds a role in it.
• A gateway key, rcv_live_…, authenticates your applications to the gateway. An organization can have many; each is a separate credential with its own name, its own caps and its own line in your attribution.
• A provider key is your credential with OpenAI or Anthropic. You add it once, under Settings → Organization → API keys → Provider keys, and the gateway signs your forwarded calls with it. It is "Sealed with envelope encryption at rest. Plaintext only in flight to your provider." Your code never sends it to Recovea.
• A project is a name for a slice of your spend. An Owner or Admin can assign a key to a project, and a request can name one in x-recovea-project; spend can then be cut by project. A cap is set on the organization or on a key, not on a project.

The secret is shown exactly once, and everything else about a key is a display row. Recovea stores a peppered HMAC of an rcv_live_ key plus its display metadata, a prefix and the last four characters, and nothing else. There is no endpoint, no log line and no error body that can hand the plaintext back, because it is not there to hand back.

A gateway key has two identifiers, and they are different things. The secret, rcv_live_ followed by 40 lowercase hex characters, is what your applications send; it is shown once. The record id, key_ followed by 32 hex characters, is what the platform and the API use to name the key, for example when a cap is set on it. A cap never names the secret.

Where keys live

Who may do it. Minting, rotating and revoking a key is an Owner, Admin or Member act. A Viewer sees the list and cannot mint, and the platform says so rather than offering a button the server would refuse. A Billing member does not see the key list at all, and the page names the role instead of failing.

A Member can mint, rotate, revoke and cap any key in the organization, not only keys they minted. Nothing records who minted a key, and the server's fence is the route, checked before the key is loaded.

Minting

Mint key takes one thing, a name. The name is for you: it is what the Limits page and every cap row call the key, and it seeds the cap's derived name ("Production, weekly").

Then the reveal step, which happens once:

• the plaintext rcv_live_… secret, with a copy control;
• "Recovea stores a hash of this key, never the secret itself."
• the optional cap step (below);
• Skip / Done.

The response body of POST /platform/v1/keys carries secret and is the only place it ever appears. GET /platform/v1/keys answers display metadata only — id, name, display, createdAt, lastUsedAt, status, and the key's optional project. A key with no name is refused with a 400; there is nothing to call a nameless key on any of the four screens it appears on.

The cap at mint time

The reveal step carries the whole cap form, locked to the key that was just minted:

Set a cap on this key (optional) — a cap on this key alone. You can set or change it later from the key's row.

Three things about it are deliberate:

• It attaches to the reveal and never to the name step. The key id does not exist until the mint returns, and a cap form on the name step would have nothing to lock onto.
• Skipping is the default path and costs one click. The footer button reads Skip.
• The cap is born disarmed, exactly like every other cap. Minting arms nothing, and a yearly cap asks for confirmation here on the same terms as everywhere else.

It is the same four-field form as everywhere else: amount and window, Enforce a hard stop, Spend alerts, Alert recipients (Where a cap is set).

Caps on the key row

The keys table carries a Cap column, and it is one line per cap, not one per key:

$150.00 · Per week · $51.60 left · [ ●───] Armed

• A key may hold several caps, a daily cap and a lifetime cap at once, so each has its own line and its own Edit.
• The line links to that cap on the Limits page, so the key row is a shortcut and the Limits page is the home, with the cap's bar and reset line.
• The button beside the row adds a new cap and says so: Cap on a key with none, Add a cap on a key that already has one.

Rotating

Rotate mints the successor and returns its plaintext once, exactly like a mint. The predecessor is not killed: it moves into a grace window and keeps working, so the cutover has no gap.

The platform says so at the moment of the act:

The old key still works for 60 minutes — rotation keeps the previous key alive for an hour so you can cut over with no downtime. If you are rotating because the old key leaked, revoke it now instead of waiting.

The store's rotate is atomic: the successor is inserted and the predecessor moved into its grace window in one motion, so there is never a moment with an orphan successor or a gap in service. When the window closes the predecessor auto-revokes, on the store's own sweep — nothing needs to be clicked.

Losing a race with a concurrent revoke is a 409, not a half-rotation. Nothing is persisted and the rotation did not happen.

Revoking

Revoke is immediate and terminal. There is no revoked-to-active edge in the status machine, so nothing rotates a revoked key back into service and nothing un-revokes it. Revoking a key that is already revoked is an idempotent no-op rather than an error; an id that was never in this organization is an honest 404.

The gateway hears within seconds: a mint, a rotation or a revocation pushes the key table to the gateway at once, and a push every five seconds backstops it.

What a revoked key keeps

A revoked key routes nothing, so offering to cap it is offering a control over nothing — and its windowed thresholds cannot re-cross, because there is no traffic and no spend to warn about. What it does not lose is the record: the caps that were on it still render, because what a key was bounded by is part of what it did.

The two sentences above are about the key's own row. On the Limits page the Caps on keys table asks only about your role, so a revoked key's cap can still be edited and deleted from there; what the Limits page withholds is a new cap — a revoked key is not offered in the Add a cap picker. Disarming a key's cap is reachable from both.

See also

• Where a cap is set: the four-field cap form, the five windows, the Limits page, and who may change which cap.
• Alert thresholds: the percentages a cap warns at and the dollar figure on each row.
• Roles: what each of the five roles may do.