Skip to main content
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.
  • 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 tagsThe Create secret dialog with Name LOYALTY_API_KEY, a hidden Value, a description and tags
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 atThe Secrets page with CRM_API_KEY, BOOKING_TOKEN and MAPS_KEY, showing Name, Tags and Created at
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.

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_KEYThe Select secret dialog listing CRM_API_KEY, BOOKING_TOKEN and MAPS_KEY
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.
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.

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.

Connect an API

Authentication and headers for API requests.

Connect an MCP server

Connect a server that needs a key.

Environment variables

Different values for dev, staging and prod.

Roles and permissions

Who can see and change secrets.