# Secrets

> Store an API key or token so agents' tools can use it without ever seeing it, choose which hosts may receive it, and replace it later.

Source: https://docs.whorl.work/agents/secrets

A secret is a key, token or password that a tool needs, such as an API key. Whorl stores it encrypted. Tools read it by name, and nobody can see the value again after it is saved, including you.

Never paste a key into a Thread, an instruction or a file. Agents are told never to ask for a secret value in chat. If an agent needs one, it tells you the name to use, and you enter the value yourself.

## Add a secret

1. Open the **Agents** card for the layer that should have it. See [Agents and setup](/agents/setup).
2. On the **Tools can read** line, choose **Add secret**.
3. In the dialog, which reads "Save _value_ as _name_ for _hosts_", fill in:
   - **Secret value**: the key. The field is hidden as you type.
   - **Secret name**: capital letters, numbers and underscores, such as `API_KEY` or `LINEAR_API_KEY`.
   - **Hosts that may receive it**: the websites the secret may be sent to, such as `api.linear.app`. Separate several with commas.
4. Choose **Save secret**.

Whorl refuses a host that is not a plain HTTPS address, and a secret can name up to 16 hosts.

## How tools use a secret

A tool never sees the value. When it needs to call a service, it asks Whorl to make the request, and Whorl adds the secret to the request as a header. The secret goes only to a host you listed. Requests to any other address are refused.

By default the secret is sent as an `Authorization` header with the prefix `Bearer`.

An MCP server that needs a key keeps its own saved key. See [Tools, MCP servers and connectors](/agents/tools).

## Which layer

A secret belongs to a layer: the company, a Space, you or a Captain. The same name at a closer layer replaces the outer one. Tools in a Space read the Space's secrets. A Captain's tools read the Captain's. Choose the narrowest layer that reaches everyone who needs it. See [Agents and setup](/agents/setup).

## Replace a secret

To change a value, add the secret again with the same name at the same layer and enter the new value. The old value is replaced, and nobody sees either one.

## Related

- [Agents and setup](/agents/setup)
- [Tools, MCP servers and connectors](/agents/tools)
- [Plugins](/agents/plugins)