Managing secrets

Secrets let you store sensitive data such as API keys, passwords, tokens, and other credentials securely and use them in your agent's tool calls without hardcoding them in prompts or exposing them in chat history.

Types of secrets

Admin-managed secrets

If you manage secrets for your organization, you store these encrypted on the server. Use them when:

• You need to share a secret across multiple users
• You are setting up organization-wide tool authentication
• You want secrets managed centrally

You can scope admin secrets to a specific agent or share them across your entire organization.

User-provided secrets

You keep these encrypted in your browser (not on the server). Use them when:

• You need your own credentials (for example, a personal API key)
• You do not want your secret stored on the server
• You want to manage your own access

Creating a secret

1. Go to your agent's Tools page and click Prompt Secrets, or click Manage > Manage Secrets in the agent editor.
2. Click Add Secret.
3. Fill in:
   • Name—A unique identifier such as API_KEY or DB_PASSWORD. Your agent uses this to reference the secret.
   • Description (optional)—A note about what this secret is for.
   • Value—The actual secret. It is encrypted when you save it.

Using secrets in your agent

Once you create secrets for an agent, your agent automatically knows about them. You can optionally add instructions in your agent's prompt to guide how they are used:

When making API calls, use {{API_KEY}} as the authentication token.
When connecting to the database, use {{DB_USERNAME}} and {{DB_PASSWORD}} as credentials.

When your agent makes a tool call, placeholders such as {{API_KEY}} are replaced with the actual secret values immediately before the tool runs. You will not see the real values in chat history or in the conversation.

Note: You enter the name without braces (for example, API_KEY), but you reference it in tool calls using the {{NAME}} format.

Secret scoping

• Agent-specific secrets—You create these from your agent's Tools or Instructions page. Only that agent can use them.
• Organization-wide secrets—You can use them from any agent in your organization.

Security

• Your secrets are encrypted at rest.
• Your secrets are only decrypted when a tool runs—they are never stored in plain text in the database, chat history, or agent configuration.
• When you receive tool outputs, any secret values that appear in the output are masked automatically with ****.
• You can create and manage secrets only if you have the appropriate organization-level permissions.
• If you use user-provided secrets, they never leave your browser in unencrypted form.