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

# Secrets: store credentials and use them in tools

> Store API keys and passwords once per project as secrets, reference them in tools with {{secrets.NAME}}, and know where they are filled in on calls.

A secret is a credential, such as an API key or a token, that you store once in your project and reference from your tools by name. The value is never shown again after you save it, and you can replace it in one place when it changes. This page shows how to create and manage secrets, and where you can use them.

## Before you start

* To open **Secrets** you need permission to view secrets. By default Owners and Admins can create, edit and delete them; Users can only see the list. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).
* Secrets belong to a project. Every agent in the project can use them.

## Create a secret

**1. Open Secrets**

Click **Secrets** in the sidebar.

**2. Start a new secret**

Click **Create**. The **Create secret** dialog opens.

![The Create secret dialog with Name LOYALTY\_API\_KEY, a hidden Value, a description and tags](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/tools/create-secret-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=85f191c04251592cfc40c07e5a23053b)

**3. Fill in the fields**

Enter a **Name**, such as `CRM_API_KEY`, and the **Value**. Add a **Description** and **Tags** (comma separated) if they help your team find it.

**4. Save**

Click **Create**. You won't be able to see the value again.

![The Secrets page with CRM\_API\_KEY, BOOKING\_TOKEN and MAPS\_KEY, showing Name, Tags and Created at](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/tools/secrets-list-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=d18066d179fe1470b96d3c703bfa839f)

You can also create a secret without leaving a tool: the secret picker in a tool offers **Create your first secret** when the project has none.

| Field | What it does | Rules |
| - | - | - |
| **Name** | The name you reference in tools as `{{secrets.NAME}}`. | Required. Unique in the project. Use letters, digits, underscores and hyphens only, so it can be referenced. |
| **Value** | The credential itself. | Required. Hidden after you save. |
| **Description** | A note for your team, shown under the name in the list. | Optional. |
| **Tags** | Labels to group secrets, comma separated. | Optional. |

## Use a secret in a tool

**1. Open the tool**

Open the tool in **APIs & MCPs** and click **Edit**, or open the agent's **Tool configuration** for that tool.

**2. Insert the secret**

Next to the token field or a header value, click the key icon (**Insert secret**) and pick the secret in **Select secret**. The field now holds `{{secrets.NAME}}`.

![The Select secret dialog listing CRM\_API\_KEY, BOOKING\_TOKEN and MAPS\_KEY](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/tools/insert-secret-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=2b6d62d2ed1b53e3e89dd000e2834a25)

**3. Save the tool**

Save. On calls, the agent puts the secret's value in place of the reference when it sends the request.

You can also type the reference yourself, for example a header value of `ApiKey {{secrets.CRM_API_KEY}}`.

## Where secrets are filled in

Single prompt and flow agents fill in a secret wherever a tool uses it:

* API requests: the URL, header values, token, and parameter values set in **Tool configuration**.
* MCP servers: header values and the token.
* In the app: **Test** and **Connect and list functions**.

Secret values are fetched when a call starts, so a changed value applies from the next call.

> [!WARNING]
>
> Secrets are only filled in for tools. In a prompt, greeting or message, `{{secrets.NAME}}` is left empty so the credential never reaches the model, the transcript or the call log, and the editor warns you when it finds one.

To use a secret as an environment value, see [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md).

## Manage secrets

* **Search.** **Search secrets...** finds secrets by name.
* **Edit.** In the row menu, click **Edit**. You can change the **Name**, **Description** and **Tags**. To replace the value, type it in **New value (optional)**; leave it empty to keep the current one. Click **Save changes**.
* **Delete.** In the row menu, click **Delete**, then **Delete** in the dialog. This can't be undone.

## Good to know

* Renaming or deleting a secret doesn't update the tools that reference it. Update those tools too: a reference to a secret that doesn't exist is filled in as empty, so the request goes out without the credential.
* Basic authentication can't use a secret: the username and password are stored with the tool.
* Never put a secret in a web tool's parameters. Web tool arguments go to the visitor's browser.
* Secret names are case sensitive: `{{secrets.crm_api_key}}` doesn't find `CRM_API_KEY`.

## Related

> [card] [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md)
>
> Authentication and headers for API requests.

> [card] [Connect an MCP server](https://docs.tryhamsa.com/agents/tools/mcp-servers.md)
>
> Connect a server that needs a key.

> [card] [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md)
>
> Different values for dev, staging and prod.

> [card] [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md)
>
> Who can see and change secrets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.