Managing Secrets

Secrets let you securely store sensitive data — API keys, passwords, tokens, and other credentials — 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

These are stored encrypted on the server and managed by admins. Use them when:

• A secret should be shared across multiple users
• You're setting up organization-wide tool authentication
• The secret needs to be centrally managed

Admin secrets can be scoped to a specific agent or shared across the entire organization.

User-provided secrets

These are stored encrypted in the user's browser. Use them when:

• Each user needs their own credentials (e.g., personal API keys)
• The secret should not be stored on the server
• You want users to manage their own access

Creating a Secret

1. Navigate to the agent's Tools page, or click Manage Secrets in the agent editor.
2. Click Add Secret.
3. Fill in:
   • Name — A unique identifier like API_KEY or DB_PASSWORD. This is what the agent uses to reference the secret.
   • Description (optional) — A note about what this secret is used for.
   • Value — The actual secret. It's encrypted when saved.

Using Secrets in Your Agent

Once you create secrets for an agent, the agent automatically knows about them. You can optionally add instructions in your agent's prompt to guide how they're 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 the agent makes a tool call, placeholders like {{API_KEY}} are automatically replaced with the actual secret values just before the tool runs. The real values are never stored in chat history or shown in the conversation.

Note: Secret names are stored without braces (e.g., API_KEY), but must be referenced in tool calls using the {{NAME}} format.

Secret Scoping

• Agent-specific secrets — Created from the agent's Tools or Instructions page. Only available to that specific agent.
• Organization-wide secrets — Available to all agents in your organization.

Security

• All secrets are encrypted at rest.
• Secrets are only decrypted at the moment a tool is executed — they're never stored in plain text in the database, chat history, or agent configuration.
• When tool outputs are returned, any secret values that appear in the output are automatically masked with ****.
• Only users with the appropriate organization-level permissions can create and manage secrets.
• User-provided secrets never leave the user's browser in unencrypted form.