> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alquimia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> How Studio stores and reuses sensitive credentials securely across agents.

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.

<Tip>
  When configuring WhatsApp or Email integration channels, you'll notice credential fields don't show the stored value — only a `$secretRef` placeholder. This is intentional: credentials are write-only after they're saved.
</Tip>

## Secret scope

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

## Next steps

<CardGroup cols={2}>
  <Card title="Models Registry" icon="cpu" href="/platform/settings/models">
    See how API keys become secrets when you add a model.
  </Card>

  <Card title="Integration Channels" icon="plug" href="/platform/agent-creation/integration-channels">
    Configure WhatsApp and Email with secret-backed credentials.
  </Card>
</CardGroup>