Secrets

Secrets are named handles for sensitive values — API keys, passwords, tokens — that agents and settings need at runtime. The actual material lives in a secret vault, not inline in your agent or settings documents. The registry saves values to the vault and only keeps references (names) in configuration.

​

Why secrets matter

Without secrets, every agent that uses Anthropic’s API would need a copy of your API key in its configuration. If the key changes, you’d update every agent individually. With secrets:

1. ANTHROPIC_API_KEY is stored once in the secret vault
2. Every agent that needs it references $ANTHROPIC_API_KEY
3. If the key rotates, update the secret — all agents pick up the new value automatically

​

The $secretRef pattern

When you see a value like $ANTHROPIC_API_KEY in a field that normally holds a credential, that’s a secret reference. The $ prefix tells the Runtime to resolve the value from the secret vault at execution time. The raw secret is not kept inside agent configuration. It isn’t written to logs and isn’t shown in the Studio UI after you save; only the vault holds the sensitive payload.

​

How secrets are created

​

Automatically (recommended)

When you add a model in Settings → Models Registry and enter an API key, Studio automatically:

1. Writes the key into the secret vault under a name (e.g., ANTHROPIC_API_KEY)
2. Replaces the raw key in the model config with $ANTHROPIC_API_KEY

​

Manually

You can manage secrets directly from the Settings → Models Registry page. Edit a model and enter a new API key to rotate the secret.

​

Reusing secrets

Secrets are reusable across all configurations in a workspace:

• Models — API keys for LLM providers
• MCP Servers — credentials for authenticated MCP endpoints
• Integration Channels — WhatsApp access tokens, SMTP passwords

When a field in a modal shows a placeholder like "Leave blank to keep existing value", it means the field already holds a secret reference. You only need to enter a value if you want to replace it.

​

Secret scope

Secrets are scoped to a workspace. A secret created in one workspace is not available in another.

​

Next steps