Skip to main content
Tracecat comes with a build-in secrets manager. This allows you to store and retrieve sensitive data without exposing the value in plaintext. Secrets are encrypted at rest and stored in the database.

​
Storing secrets

Secrets are scoped to a workspace. To add a secret, navigate to the Credentials page and click on the Create Secret button.
Select the settings icon in the top right corner of the page and click on Credentials.Credentials settings

​
SECRETS context

Secrets stored in the secrets manager can be accessed using the SECRETS context: ${{ SECRETS.<name>.<key> }}. For example: 
${{ SECRETS.virustotal.VIRUSTOTAL_API_KEY }}
Tracecat will automatically replace the expression with the secret value at runtime. Retrieved secrets are removed from memory, i.e. garbage collected, after the action is executed.

​
Integrations and secrets

Check out the integrations cheatsheet for a list of pre-built integrations and their required secrets.
Authentication with pre-built integrations is handled implicitly. Pre-built integrations are associated with specific secret names and keys. For example, the VirusTotal integration requires a secret with the name virustotal and the key VIRUSTOTAL_API_KEY. Different integrations may require different required and optional keys. For example, Tracecat’s AWS integration is configured with the following secret with optional keys, but with optional=False meaning at least one of the keys must be provided: 
aws_secret = RegistrySecret(
    name="aws",
    optional_keys=[
        # Access key-based authentication
        "AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY",
        "AWS_REGION",
        # Role-based authentication
        "AWS_ROLE_ARN",
        # Profile-based authentication
        "AWS_PROFILE",
    ]
    optional=False
)

​
AWS credential

Tracecat supports three AWS credential patterns for the aws, amazon_s3, and amazon_bedrock secrets:
  • Direct credentials: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN (for temporary credentials), and AWS_REGION
  • Profile-based authentication: AWS_PROFILE and AWS_REGION
  • Cross-account role assumption: AWS_ROLE_ARN and AWS_REGION
For cross-account access, Tracecat assumes a role in your AWS account from a dedicated Tracecat executor principal. The workspace credential UI shows the three values your AWS administrator needs:
  • Tracecat AWS account ID
  • Trusted Tracecat principal ARN
  • Workspace-scoped External ID
Your user only provides the target AWS_ROLE_ARN. Tracecat manages the STS session name automatically.

​
Customer trust policy

Use a trust policy like this on the target role in the third-party AWS account: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<TRACECAT_EXECUTOR_PRINCIPAL_ARN>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<WORKSPACE_EXTERNAL_ID>"
        }
      }
    }
  ]
}
Keep the role’s permission policy minimal. For example, if you only want Tracecat to read from one bucket prefix, grant only those s3:GetObject and s3:ListBucket permissions.

​
Notes

  • Trust the dedicated Tracecat executor principal ARN, not the Tracecat account root.
  • The AWS_ROLE_SESSION_NAME key is not used by Tracecat and should not be added to new secrets.
  • Secrets remain workspace-scoped, so each workspace can use its own role ARN and External ID.

​
OAuth secrets

Unlike regular secrets, OAuth secrets are not stored in the secrets manager. Instead, they are stored in the OAuth provider’s database. To access them use the following syntax: 
${{ SECRETS.<provider_id>_oauth.<PREFIX>_[SERVICE|USER]_TOKEN }}
Where:
  • <provider_id> is the OAuth provider identifier (e.g., github, microsoft_teams)
  • <PREFIX> is the provider ID in UPPERCASE (e.g., GITHUB, MICROSOFT_TEAMS)
  • Use USER_TOKEN for authorization code flow (delegated user access)
  • Use SERVICE_TOKEN for client credentials flow (application access)
For example, to access the GitHub user token, you would use the following expression: 
${{ SECRETS.github_oauth.GITHUB_USER_TOKEN }}
OAuth secrets are scoped to a provider. To add an OAuth secret, navigate to the Integrations page and click on the Create OAuth Secret button.

​
Custom OAuth providers

When you create a custom OAuth provider, the provider ID is automatically generated by:
  1. Slugifying the name (lowercase, spaces replaced with underscores)
  2. Prepending the custom_ prefix
For example, if you create a custom OAuth provider named “My Custom App”, the provider ID becomes custom_my_custom_app. To access tokens from custom OAuth providers:
Provider NameProvider IDUser Token Expression
My Custom Appcustom_my_custom_app${{ SECRETS.custom_my_custom_app_oauth.CUSTOM_MY_CUSTOM_APP_USER_TOKEN }}
Acme APIcustom_acme_api${{ SECRETS.custom_acme_api_oauth.CUSTOM_ACME_API_USER_TOKEN }}
For service tokens (client credentials flow), replace USER_TOKEN with SERVICE_TOKEN: 
${{ SECRETS.custom_my_custom_app_oauth.CUSTOM_MY_CUSTOM_APP_SERVICE_TOKEN }}

​
Multi-tenant secrets

A common use case is to have different sets of the same secret for different tenants. For example, an MDR provider will likely have different Crowdstrike tenant IDs for each customer. Tracecat supports multi-tenant secrets via the workflow’s environment configuration. Example
1

Create a multi-tenant secret

Create a multi-tenant secret for an integration by specifying the environment key. The secret name and keys (e.g. aws and AWS_ROLE_ARN) remain the same.If no environment key is specified, the environment key defaults to default.Specify environment for secret
2

Specify workflow environment

Click on the workflow canvas. You can specify the workflow’s environment under the Configuration section.Specify workflow environment
3

Trigger multi-tenant workflows

Let’s say you have multiple sets of AWS credentials, one for each account, and you want to retrieve GuardDuty detections for each account.You can do this easily in two-steps using a looped core.workflow.execute action.First, drag out a core.workflow.execute action, then specify a loop expression that iterates over a list of AWS account IDs:
${{ for var.aws_account_id in <some-list-of-account-ids> }}
Loop expressionThen configure the core.workflow.execute action with the following inputs:
trigger_inputs: <child-workflow-inputs>
workflow_alias: <child-workflow-alias>  # You can find this in the workflows page
environment: ${{ var.aws_account_id }}  # The secret environment
Execute child workflow with variable environment