Skip to main content

​
Overview

Tracecat supports built-in OAuth integrations and custom OAuth providers. OAuth integrations expose tokens through secret expressions. OAuth integrations

​
Grant types

OAuth grant types:
  • Delegated access (authorization_code): Tracecat stores a user token after a user completes the OAuth login flow.
  • Client credentials (client_credentials): Tracecat stores a service token for server-to-server access.

​
Configure a provider

Built-in OAuth integrations are listed on the Integrations page. For custom OAuth, use Add integration → OAuth provider (or Add custom OAuth provider under Custom OAuth). Most providers require these fields:
  • Client ID
  • Client secret
  • Authorization endpoint
  • Token endpoint
  • Scopes
After you save a custom provider, connect it (complete the OAuth flow) when using delegated access so Tracecat can issue tokens.

​
Use OAuth tokens in expressions

OAuth expressions use the provider’s exact ID, not its display name.
  • Built-in providers use stable lowercase IDs assigned by Tracecat, with underscores between words, such as slack, google_drive, and microsoft_sentinel.
  • Custom providers use an ID derived from the provider name, or from the requested ID when you create one through the API. Tracecat slugifies it with underscores and prepends custom_. My Security API becomes custom_my_security_api. If that ID is already used for the same grant type, Tracecat appends _1, _2, and so on.
Append _oauth to the exact provider ID for the secret name. For the key, uppercase the complete provider ID, preserve its underscores and any numeric suffix, then append _USER_TOKEN for authorization_code or _SERVICE_TOKEN for client_credentials.
A built-in google_drive authorization-code provider and a custom custom_my_security_api client-credentials provider resolve as:
When either grant type is allowed, use a fallback:
Tracecat refreshes expiring authorization-code tokens when the provider issued a refresh token, and reacquires client-credentials tokens with the stored client credentials. The expression resolves only to the current access-token string, which may be a JWT or an opaque token, not the refresh token.

​
OAuth and actions

Registry actions reference OAuth integrations but do not create them. Configure a built-in or custom provider in Integrations first, then declare RegistryOAuthSecret (Python) or type: oauth (YAML) so the action requires that integration at runtime. See the OAuth declaration syntax and examples for Python UDFs and YAML templates.

​
OAuth and MCP

Remote MCP integrations can use an existing OAuth integration. For custom remote MCP servers:
  1. Create a custom OAuth provider.
  2. Connect that provider.
  3. Create an MCP integration and attach the connected OAuth integration.

​
FAQ

No. RegistryOAuthSecret and YAML type: oauth entries declare that the action requires an existing OAuth integration — they do not register one. Create the integration from Configure a provider (or contribute a built-in provider). Once it exists, your action can reference its tokens via ${{ SECRETS.<provider_id>_oauth... }}.
Out-of-the-box providers are implemented in the Tracecat app and get stable IDs (for example slack, google_drive) without the UI custom_ rule.
  1. Subclass AuthorizationCodeOAuthProvider or ClientCredentialsOAuthProvider under tracecat/integrations/providers/. See slack/oauth.py for a full example.
  2. Register the class in _PROVIDER_CLASSES.
  3. Keep the registry package aligned: same provider_id and grant_type in RegistryOAuthSecret (Python) and type: oauth entries (YAML) so actions resolve the same integration as the UI.