OAuth integrations provide a secure way to connect to third-party services without exposing credentials in workflows or logs. All tokens are encrypted at rest and automatically refreshed when needed.

OAuth integrations are built-in connections to third-party services that handle the complete authentication flow automatically. Unlike action templates that require manual token management, OAuth integrations provide seamless, secure access to external APIs.

Key benefits:

  • Secure credential storage - Client secrets and tokens are encrypted at rest
  • Automatic token refresh - Expired tokens are refreshed in the background
  • Dynamic scope management - Configure only the permissions you need
  • Workspace isolation - Each workspace has separate integration configurations

​
OAuth grant types

Tracecat supports two OAuth 2.0 grant types for different authentication scenarios. The grant type must be selected when configuring each provider and affects both the authentication flow and available features.

​
Authorization Code Flow (Delegated User)

The standard OAuth flow where users are redirected to the provider to grant permissions. Best for:

  • Delegated user access - Actions performed on behalf of a specific user
  • Interactive authentication - Requires user consent and login
  • Broad API access - Full access to user resources with appropriate scopes

Examples: Accessing a user’s Microsoft OneDrive files, sending Slack messages as a specific user

​
Client Credentials Flow (Service Account)

Direct machine-to-machine authentication using client credentials only. Best for:

  • Service account access - Actions performed by the application itself
  • Service authentication - No user interaction required
  • System integration - Background processes and automated workflows

Examples: Organization-wide Microsoft Teams channel management, system-level GitHub repository access

Each provider requires a specific grant type to be selected during configuration. This choice determines:

  • The authentication flow (user redirect vs direct authentication)
  • Available API permissions and scopes
  • Token refresh behavior

Some providers support both flows while others may only support one. The provider’s setup instructions will indicate which grant types are available.

​
Setting up OAuth integrations

Before configuring OAuth integrations in Tracecat, you must first create an OAuth application with your chosen provider (Microsoft, Google, GitHub, etc.). This process is the same for both Authorization Code and Client Credentials flows:

  1. Create OAuth application - Register a new application in your provider’s developer console
  2. Configure redirect URI - Set the callback URL that Tracecat will provide during setup
  3. Obtain credentials - Copy the client ID and client secret from your OAuth application
  4. Set permissions - Configure the required scopes and permissions for your use case

Each provider has specific setup requirements. Tracecat provides direct links to setup guides in the configuration interface for each OAuth integration.

1

Navigate to integrations

Go to your workspace and navigate to the integrations page. Select the OAuth provider you want to configure from the available list. Each grant type is defined as a separate OAuth integration - you can distinguish between them by the lock icon (Client Credentials) or user icon (Authorization Code) displayed on each integration tile. This allows you to configure multiple integrations for the same provider with different grant types and credentials.

2

Configure the provider

Configure the following settings for your selected provider:

  • Client ID - OAuth application client ID from the provider
  • Client Secret - OAuth application client secret (encrypted when saved)
  • Additional Scopes - Custom scopes beyond the base requirements (optional)

Each provider includes setup instructions with links to their developer documentation. Follow the provider’s guide to create an OAuth application and obtain your client credentials.

3

Complete authentication

The authentication process depends on your selected grant type:

Authorization Code Flow

Click “Connect with OAuth” to complete the authorization:

This redirects you to the provider’s authorization page where you grant permissions to Tracecat.

Client Credentials Flow

Click “Fetch Token” to verify your client credentials. No user authorization is required - the connection uses your application’s credentials directly.

4

Verify connection

Once connected, the integration status shows as “Connected” with details about granted scopes and token expiration:

​
Managing scopes

OAuth integrations use a two-tier scope system:

​
Base scopes

Required permissions that every integration needs for basic functionality. These are automatically included and cannot be removed.

​
Additional scopes

Optional permissions you can add for extended functionality. Use the scope input to add custom scopes beyond the base requirements.

Only add scopes you actually need. Extra permissions increase security risk and may require additional approval from your organization.

​
Integration status

OAuth integrations have three possible states:

1

Not Configured

No client credentials have been set up. Click “Configure Integration” to get started.

2

Configured

Client credentials are saved but authentication hasn’t been completed. For Authorization Code flow, click “Connect with OAuth”. For Client Credentials flow, click “Test Connection”.

3

Connected

Successfully authenticated and ready to use in workflows. For Authorization Code flow, tokens are automatically refreshed as needed.

​
Managing integrations

Once configured, you have two options for managing OAuth integrations:

​
Disconnect

Removes the OAuth tokens while preserving your configuration (client ID, secret, and scopes). Use this when:

  • You want to re-authenticate with different permissions
  • The current authentication has issues but you want to keep the configuration
  • You need to switch which account is connected

​
Delete

Completely removes the integration including all configuration and tokens. Use this when:

  • You no longer need the integration
  • You want to set up with entirely different credentials
  • You’re switching to a different OAuth application

​
Supported providers

Microsoft Graph

Access Office 365, Azure AD, and Microsoft services

Microsoft Teams

Channel management and team collaboration

Google Workspace

Connect to Gmail, Drive, Calendar, and Google services

GitHub

Repository management and organization access

Slack

Channel messaging and workspace integration

Don’t see your provider? OAuth integrations are extensible - check our contributing guide to learn how to add new providers.

​
Using in workflows

Once connected, OAuth integrations work seamlessly with action templates and Python UDFs. The integration handles token retrieval automatically - no need to manage credentials in your workflows.

# Example: List files from Microsoft OneDrive
- ref: list_files
  action: tools.microsoft_graph.list_drive_files
  args:
    drive_id: "b!abc123"
    folder_path: "/Documents"

The tools.microsoft_graph.list_drive_files action automatically uses your connected OAuth integration for authentication.

​
Troubleshooting

​
Security considerations

OAuth integrations have access to external services with the permissions you grant. Follow security best practices:

  • Only grant minimum required scopes
  • Regularly review connected integrations
  • Rotate client secrets periodically
  • Monitor integration usage in audit logs

All OAuth credentials and tokens are encrypted using workspace-specific encryption keys. Tokens are never logged or exposed in workflow outputs for security.