Scopes: Global vs Organization

Scope determines whether a resource is shared across the entire platform (global) or belongs to a specific organization.

Understanding Scope

Resources in Bifrost exist at two levels:

• Global - Available to all organizations on the platform
• Organization - Specific to one organization, isolated from others

Tip

Most resources you work with will be globally scoped so you can maximize reusability. Scope things to organizations that are truly specific to that oranization, like automations or forms you’re developing specifically for them.

OAuth Connections

Each organization can have its own OAuth connections with its own credentials:

# Your organization's Microsoft Graph connection
# Uses YOUR Entra ID app credentials
# Not visible to other organizations
response = await oauth.get_token("microsoft-graph")

Secrets

Secrets themselves are not scoped, but the configurations they’re tied to are.

Configuration

Organization-specific settings:

# Your organization's configuration
timezone = config.get("timezone")  # e.g., "America/Denver"
department = config.get("default_department")

When Global Scope is Used

1. Shared platform services - Services managed centrally by the platform
2. Default configurations - Fallback settings when organization doesn’t have its own
3. Platform-wide integrations - Connections managed by platform admins

How Scope Works in Your Workflows

When you access resources in a workflow, Bifrost automatically uses your organization’s context:

from bifrost import workflow, oauth, config

@workflow(name="example")
async def example(context):
    # Uses YOUR organization's OAuth connection
    graph = await oauth.get_token("microsoft-graph")

    # Gets YOUR organization's config
    timezone = config.get("timezone")

1. Your workflow executes in the caller’s context

2. All resources are automatically scoped to their organization

3. Data is isolated - your workflow ultimately decides what to do based on this information

Scope Resolution

Bifrost looks for resources in this order:

1. Organization-level - Your organization’s specific resource
2. Global-level - Platform-wide fallback (if exists)
3. Error - Resource not found

Example:

# Looking for config value "smtp_server"
smtp = config.get("smtp_server")

# 1. Check: Does my org have "smtp_server"? → Yes, use it
# 2. (If not found) Check: Is there a global "smtp_server"? → Use it as fallback
# 3. (If still not found) Return None or default value

TL;DR

• Put resources like configs, forms and OAUTH connections in global or a specific organization
• The Bifrost SDK will automatically pull organization-specific things like configs first and fallback on global
• It’s on you as the workflow developer to decide HOW to use context in the workflow, but the SDK will scope resources appropriately for you if you put them in the right place