---
title: "Secrets and variables"
description: "Pass Tracecat secrets and workspace variables to preset agent tool calls securely: scope credentials per agent run and inject values without exposing them to the model."
icon: "lock"
---

## Overview

Preset agents can reference secrets and variables using Tracecat expression syntax.
Include `${{ SECRETS.<name>.<key> }}` or `${{ VARS.<name>.<key> }}` in a preset agent's saved instructions so the agent passes them as tool arguments at runtime.

## Security

Preset agent tool calls go through a secure server-side proxy.
The LLM only sees the raw expression placeholder (e.g. `${{ SECRETS.threatintel.API_KEY }}`). The actual secret values are injected server-side at the tool execution layer after the model responds, so the LLM never has access to your credentials.

<Warning>
`ai.action` and `ai.agent` actions do **not** support secure secrets injection. Secret and variable expressions are evaluated immediately in workflow action inputs and will be exposed to the LLM.
</Warning>

## Secrets

Use `${{ SECRETS.<secret_name>.<key> }}` to reference a secret stored in your workspace credentials.

In a workflow action this looks like:

```yaml
- ref: triage_alert
  action: ai.preset_agent
  args:
    preset: security-triage
    user_prompt: |
      Look up the reputation of this IP address:

      ${{ TRIGGER.source_ip }}
```

Where the `security-triage` preset instructions contain:

```text
You are a security triage agent.

When you make HTTP requests to the threat intel API, pass
`${{ SECRETS.threatintel.API_KEY }}` in the Authorization header
as a Bearer token.

Do not print or return secret values in your final answer.
```

## Variables

Use `${{ VARS.<variable_name>.<key> }}` for non-sensitive configuration such as base URLs, project IDs, or channel names.

In a workflow action:

```yaml
- ref: triage_alert
  action: ai.preset_agent
  args:
    preset: security-triage
    user_prompt: |
      Investigate this alert and file a ticket with your findings:

      ${{ TRIGGER.alert }}
```

Where the `security-triage` preset instructions contain:

```text
You are a security triage agent.

When you call the threat intel API, use `${{ VARS.threatintel.base_url }}`
as the base URL.
When you file tickets, use `${{ VARS.ticketing.project_id }}` as the
project ID and `${{ VARS.ticketing.base_url }}` as the base URL.
```

## Secrets and variables

Use secrets for credentials and variables for everything else.

Full workflow example:

```yaml
- ref: investigate_and_respond
  action: ai.preset_agent
  args:
    preset: security-triage
    user_prompt: |
      Investigate this alert:

      ${{ TRIGGER.alert }}
    max_tool_calls: 10
```

Where the `security-triage` preset instructions contain:

```text
You are a security triage agent. Investigate the alert, enrich it,
and file a ticket.

Credentials:
- Threat intel API key: `${{ SECRETS.threatintel.API_KEY }}`
- Ticketing API key: `${{ SECRETS.ticketing.API_KEY }}`

Configuration:
- Threat intel base URL: `${{ VARS.threatintel.base_url }}`
- Ticketing base URL: `${{ VARS.ticketing.base_url }}`
- Ticketing project ID: `${{ VARS.ticketing.project_id }}`

Steps:
1. Look up the source IP using the threat intel API.
2. File a ticket with your findings in the ticketing system.

Do not print or return secret values in your final answer.
```

## OAuth secrets

OAuth tokens follow a different naming convention. The secret name is `<provider_id>_oauth` and the key is the provider ID in uppercase plus `_USER_TOKEN` or `_SERVICE_TOKEN`.

```yaml
# authorization_code grant (delegated user access)
${{ SECRETS.<provider_id>_oauth.<PROVIDER_ID_UPPER>_USER_TOKEN }}

# client_credentials grant (service-to-service)
${{ SECRETS.<provider_id>_oauth.<PROVIDER_ID_UPPER>_SERVICE_TOKEN }}
```

In a workflow action:

```yaml
- ref: query_sentinel
  action: ai.preset_agent
  args:
    preset: sentinel-analyst
    user_prompt: |
      Query Microsoft Sentinel for recent incidents related to this IP:

      ${{ TRIGGER.source_ip }}
```

Where the `sentinel-analyst` preset instructions contain:

```text
You are a security triage agent.

When you make HTTP requests to the Microsoft Sentinel API, pass
`${{ SECRETS.microsoft_sentinel_oauth.MICROSOFT_SENTINEL_USER_TOKEN }}`
in the Authorization header as a Bearer token.

Do not print or return secret values in your final answer.
```

See [OAuth integrations](/automations/integrations/oauth-integrations) for setup and the full list of built-in providers.

## Related pages

- [Secrets](/automations/core-concepts/secrets) — create and manage workspace secrets
- [Variables](/automations/core-concepts/variables) — create and manage workspace variables
- [Expressions](/automations/core-concepts/expressions) — full expression syntax reference
- [AI agent](/agents/ai-agent) — `ai.agent` and `ai.preset_agent` reference
- [OAuth integrations](/automations/integrations/oauth-integrations) — OAuth setup and providers
