> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recovea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization and keys

Your organization, the gateway keys it mints, and the project a key can carry: what each one is and who may change it.

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](https://docs.recovea.ai/concepts/roles/) 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

| Act | Where |
| --- | --- |
| Mint, rotate, revoke | Settings → Organization → **API keys** |
| A cap on one key, at mint time | The mint dialog, on the reveal step |
| A cap on one key, later | The key's own row, **Cap** / **Add a cap** — or Settings → Organization → **Limits**, *Caps on keys* |
| Review every cap on every key | Settings → Organization → **Limits** |

**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](https://docs.recovea.ai/products/caps/#the-cap-form)).

## 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.

|  |  |
| --- | --- |
| Default grace | **60 minutes** |
| Maximum grace | **10080 minutes, seven days** |
| Out of range | `400 invalid_request` |
| Rotating a key that is not **active** | `409 invalid_state` — the status machine has no such edge |

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

| Keeps | Loses |
| --- | --- |
| Its row, marked **Revoked** | **Rotate** and **Revoke** |
| Its caps, rendered in the Cap column as the record of what was in force | The cap controls on that row — no Edit, no Delete, no switch, no new cap |
| Its place in the ledger, and the receipts of every request it made | A place in the key picker on Limits, *Add a cap* |

**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](https://docs.recovea.ai/products/caps/): the four-field cap form, the five windows, the Limits page, and who may change which cap.
- [Alert thresholds](https://docs.recovea.ai/concepts/alert-thresholds/): the percentages a cap warns at and the dollar figure on each row.
- [Roles](https://docs.recovea.ai/concepts/roles/): what each of the five roles may do.