Secrets

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 encrypted directly with the tenant’s master key using AEAD (XChaCha20-Poly1305), with a fresh random nonce generated per write and the secret’s name bound in as additional authenticated data. 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.
File mount credentials: e.g. an access key for a mounted bucket.

{
  "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.

Secret names must match ^[a-zA-Z0-9_-]{1,64}$ (letters, digits, underscore, and hyphen, 1 to 64 characters); any other name is rejected with a 400 before the secret is stored.

Rotating a secret is a full replace, not a plaintext-only patch: the PUT request must resend the existing key and description alongside the new plaintext, or those fields are overwritten with an empty value. PUT on a name that does not yet exist creates it rather than returning a 404.

# 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; key and description must be resent
curl -X PUT https://api.orcapods.ai/api/secrets/openai-prod-key \
  -H "Authorization: Bearer ao_..." \
  -H "Content-Type: application/json" \
  -d '{"key":"OPENAI_API_KEY","plaintext":"sk-new-value...","description":"Prod OpenAI key"}'

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.

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. The two failure modes differ: if the vault is wired but the named secret does not exist, resolution fails immediately with a hard error, as described above. If the vault itself is not configured at all (the degraded mode this section describes), a secret:// reference is passed through verbatim as literal text, and the failure only surfaces later when the downstream MCP server rejects the unresolved value as bad credentials.

Manage secrets

Create, rotate, and delete secrets with the CLI.

MCP Integration

Use secret:// in MCP server headers.

Roles & Access

Why Secrets is admin-only.

Get Started

Core Concepts

Guides

Runbooks

Overview

Referencing a secret: `secret://`

Operations

Access

Self-hosting note

Manage secrets

MCP Integration

Roles & Access

​Overview

​Referencing a secret: secret://

​Operations

​Access

​Self-hosting note

​Related

Manage secrets

MCP Integration

Roles & Access

Overview

Referencing a secret: `secret://`

Operations

Access

Self-hosting note

Related