> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Secrets
> A per-tenant encrypted secret vault. Reference values as secret:// in MCP headers and file mounts — plaintext is never displayed after creation.
## Overview
Secrets is a **per-tenant, encrypted vault** for the credentials your agents need — API keys, tokens, connection strings, and similar. Each secret has a **name**; its plaintext is stored under **envelope encryption** (each value is encrypted with a data key that is itself wrapped by a master key). After you create a secret, **its plaintext is never displayed again** — not in the dashboard, not through the API, and it is never logged.
On the hosted product at **app.orcapods.ai**, Secrets is always available — there is nothing to configure.
## Referencing a secret: `secret://`
Instead of pasting a credential into a config field, you store it once and reference it by name using the `secret://` scheme. Orca resolves the reference to the plaintext **at request time**, so the raw value never lives in your profile or logs.
The two most important places this matters:
* **MCP server header values** — e.g. an `Authorization` header on a [managed or self-configured MCP server](/concepts/mcp-integration).
* **File mount credentials** — e.g. an access key for a mounted bucket.
```json theme={null}
{
"headers": {
"Authorization": "Bearer secret://openai-prod-key"
}
}
```
A `secret://` value is resolved as a whole — you cannot mix `secret://` and other interpolation like `${VAR}` in the same field. If a referenced secret cannot be resolved, the request **fails loudly by design** rather than silently sending an empty credential.
## Operations
| Operation | What it does |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Create** | Store a new secret: `name`, optional canonical **key** (the variable it populates, e.g. `ANTHROPIC_API_KEY`), optional **description**, and the **plaintext**. |
| **Rotate** | Replace the plaintext of an existing secret in place — the name and every `secret://` reference to it keep working. |
| **Delete** | Remove the secret. References to it will then fail to resolve. |
```bash theme={null}
# Create a secret
curl -X POST https://api.orcapods.ai/api/secrets \
-H "Authorization: Bearer ao_..." \
-H "Content-Type: application/json" \
-d '{"name":"openai-prod-key","key":"OPENAI_API_KEY","plaintext":"sk-...","description":"Prod OpenAI key"}'
# Rotate (replace the plaintext) — the name and all references are unchanged
curl -X PUT https://api.orcapods.ai/api/secrets/openai-prod-key \
-H "Authorization: Bearer ao_..." \
-H "Content-Type: application/json" \
-d '{"plaintext":"sk-new-value..."}'
```
Reads return **metadata only** (name, key, description, timestamps) — never the plaintext.
## Access
Secrets are **admin-only**. Only `owner` and `admin` roles can list, create, rotate, or delete them; members and viewers cannot. See **[Roles & Access](/concepts/access-control)**.
## Self-hosting note
When you self-host, the vault requires both a database (`POSTGRES_DSN`) and a **master key** (`AGENT_ORC_MASTER_KEY`) to be configured. Without them the secrets routes run in a degraded mode and return `503`. As above, an unresolved `secret://` reference is treated as a hard error, so a misconfigured vault surfaces immediately instead of leaking empty credentials into requests.
## Related
Create, rotate, and delete secrets in the dashboard.
Use secret:// in MCP server headers.
Why Secrets is admin-only.