# Vault

Vault is an encryption service for data you keep about your customers: API tokens, personal data, documents. Each organization gets its own named keys, rotation keeps old data readable, and when the organization (or your environment) has a [customer-managed key](/byok/), Vault keys are protected by it too.

## Keys

- `POST /v1/vault/keys` creates a named key for an organization (scope `vault:write`).
- `GET /v1/vault/keys?organization=…` lists them with their current version (`vault:read`) and their `usage` over the last 30 days: `encrypts`, `decrypts` and `last_used_at`. Usage is counted on a best-effort basis and is not a billing record.
- `POST /v1/vault/keys/{key}/rotate` adds a new version. New data uses it; older ciphertexts still decrypt.

## Encrypt and decrypt

`POST /v1/vault/encrypt` with `organization`, the key name, the `plaintext` and an optional `context` returns a `ciphertext`, the key ID and its version. `POST /v1/vault/decrypt` with the `organization`, the `ciphertext` and the same `context` returns the plaintext. Both need `vault:use`. A ciphertext from another organization, a different context or a revoked customer key fails with [`vault_decrypt_failed`](/errors/vault_decrypt_failed/); Vault never falls back to a weaker key.

From the CLI: `ohauthcat vault encrypt --organization org_123 --key payroll --plaintext-file secret.txt` and `ohauthcat vault decrypt --organization org_123 --ciphertext …`.

## Objects

For values you would rather not store yourself, Vault keeps versioned encrypted objects:

- `PUT /v1/vault/objects/{name}` stores a new version under an organization's key.
- `GET /v1/vault/objects/{name}` reads the latest version, or one you name.
- `GET /v1/vault/objects/{name}/versions` lists versions (metadata only).
- `DELETE /v1/vault/objects/{name}` deletes every version.

Vault routes have their own rate limit, lower than the general API key limit.
