​
OAuth grant types

Tracecat supports two OAuth 2.0 grant types for different authentication scenarios:
  • Authorization Code Flow (Delegated User): OAuth flow where a human user is redirected to the provider to grant permissions.
  • Client Credentials Flow (Service Account): Machine to machine authentication using credentials only.

​
Setup guide

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. (If needed) 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.

​
Managing scopes

Only add scopes you actually need. Extra permissions increase security risk and may require additional approval from your organization.
OAuth integrations use a two-tier scope system:
  1. Base scopes - Required permissions that every integration needs for basic functionality. These are automatically included and cannot be removed.
  2. Additional scopes - Optional permissions you can add for extended functionality. Use the scope input to add custom scopes beyond the base requirements.
Each provider defines allowed scope patterns to prevent invalid or potentially dangerous permissions. If you enter an invalid scope, you’ll see a validation error with the expected patterns.Common validation patterns:
  • Microsoft Graph: https://graph.microsoft.com/.default or specific resource scopes
  • Google APIs: Service-specific scopes like https://www.googleapis.com/auth/drive.readonly
  • GitHub: Repository and organization permissions like repo, read:org

​
Integration status

OAuth integrations have three possible states:
1

Not configured

No client credentials have been set up. Go into the configurations to add your client credentials.
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” or “Fetch token”.
3

Connected

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

​
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

OAuth tokens have limited lifespans. Tracecat automatically refreshes expired tokens using refresh tokens.If refresh fails, you may need to re-authorize by clicking “Connect with OAuth” again.
If workflows fail with permission errors, check that your integration includes the required scopes.You can update scopes in the configuration tab and re-authorize to grant additional permissions.
Verify your OAuth application configuration with the provider:
  • Redirect URI matches the one shown in Tracecat
  • Client ID and secret are correct
  • OAuth application is enabled and published