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

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

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.

Manage secrets

Create, rotate, and delete secrets in the dashboard.

MCP Integration

Use secret:// in MCP server headers.

Roles & Access

Why Secrets is admin-only.

Get Started

Core Concepts

Guides

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