Skip to main content

​
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

​
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.

​
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 OAuth secrets in UDFs

This is how you would retrieve an OAuth secret in an UDF: 
import requests
from tracecat_registry import RegistryOAuthSecret, registry, secrets

github_oauth_secret = RegistryOAuthSecret(
    provider_id="github",
    grant_type="authorization_code",
)

@registry.register(
    description="List repositories",
    namespace="tools.github",
    secrets=[github_oauth_secret],
)
def list_repos():
    # Retrieve the OAuth token to use
    token = secrets.get(github_oauth_secret.token_name)
    response = requests.get(
      "https://api.github.com/user/repos",
      headers={"Authorization": f"Bearer {token}"}
    )
    response.raise_for_status()
    return response.json()

​
Using OAuth secrets in action templates

This is how you would use an OAuth secret in an action template: 
type: action
definition:
  title: List repositories
  description: List repositories from GitHub.
  display_group: GitHub
  doc_url: https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repositories-for-the-authenticated-user
  namespace: tools.github
  name: list_repos
  secrets:
    - type: oauth
      provider_id: github
      grant_type: authorization_code
  expects:
    - ref: list_repos
      action: core.http_request
      args:
        url: https://api.github.com/user/repos
        method: GET
        headers:
          Authorization: Bearer ${{ SECRETS.github.GITHUB_USER_TOKEN }}
  returns: ${{ steps.list_repos.result.data }}

​
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
⌘I