Integrations

Integrations are the bridge between Bifrost and external APIs. They combine OAuth credentials, configuration, and organization-specific settings into a unified system.

Integrations vs Configs — when to use which

Integrations are the preferred way to manage external connections — even for non-OAuth services. The integration entity gives you a clear “here are my external connections” surface and supports per-org overrides via IntegrationMapping.

Configs are for arbitrary org-scoped or global key-value pairs that don’t represent a connection — feature flags, default labels, retry counts, anything that isn’t an outgoing connection identity.

Per-org override pattern: link an integration to a Bifrost organization-list data provider in your form (a workflow you author with @data_provider that returns [{ "label": org.name, "value": org.id }] from bifrost.organizations.list()). The form’s selected org becomes the workflow’s org context, and integrations.get() then returns that org’s mapping and entity_id automatically. This is the canonical way to scope an integration call to an arbitrary org from a form.

What Are Integrations?

An integration represents a connection to an external service like Microsoft Graph, HaloPSA, or any REST API. Each integration can have:

For OAuth integrations, the list rolls the default connection and organization overrides into one status. Connected means every connection is healthy, Degraded means the integration has both healthy and failed connections, Failed means every connection failed, and None means no connection exists. Select the status to open the connection-count breakdown.

Integrations provide:

• OAuth credentials - Access tokens managed by Bifrost
• Configuration - API keys, base URLs, timeouts
• Entity mapping - Organization-specific tenant IDs or company IDs
• Generated SDK - Auto-generated Python client from OpenAPI spec

Two-Level Configuration

Integrations support configuration at two levels:

Level	Scope	Use Case
Integration defaults	All organizations	Base URLs, default settings
Organization overrides	Single organization	Tenant-specific IDs, custom endpoints

When your workflow requests an integration, Bifrost merges defaults with org-specific overrides:

from bifrost import integrations

# Get merged configuration
integration = await integrations.get("HaloPSA")
base_url = integration.config.get("base_url")  # Merged from defaults + org
tenant_id = integration.entity_id               # Org-specific

OAuth Management

Integrations replace the legacy oauth module with better organization:

# Old approach (deprecated)
# from bifrost import oauth
# conn = await oauth.get("Microsoft_Graph")

# New approach
from bifrost import integrations

integration = await integrations.get("Microsoft_Graph")
if integration and integration.oauth:
    token = integration.oauth.access_token

Note

OAuth tokens are automatically refreshed by Bifrost. You always get valid credentials.

Entity Mapping

For multi-tenant APIs, integrations track external entity IDs per organization:

Field	Description
entity_id	The external ID (tenant_id, company_id)
entity_name	Display name for the entity

Why entity_id matters

entity_id is the routing key for org-scoped OAuth and API calls. Each IntegrationMapping is a (org_id, integration_id, entity_id) triple, and the entity_id becomes the connection identity downstream API calls use to address the right tenant or customer record:

• Microsoft Graph → entity_id is the Entra ID tenant_id
• HaloPSA → entity_id is the HaloPSA company_id
• ConnectWise / Autotask → entity_id is the customer/company key

A single integration can serve many Bifrost organizations because each one carries its own entity_id in its mapping. Without that mapping, every org would share one set of credentials and target one external tenant — defeating the per-customer scoping that MSPs need.

Bifrost Org
    │
    ▼
IntegrationMapping(entity_id, oauth_token)
    │
    ▼
External API call (scoped to entity_id)

This enables one integration to serve multiple tenants:

# Each org has its own HaloPSA tenant
integration = await integrations.get("HaloPSA")
tenant_id = integration.entity_id  # "customer-123" for this org

Config Schema

Integrations define a schema for configuration values:

# Example schema
[
    {"key": "base_url", "type": "string", "required": True},
    {"key": "api_key", "type": "secret", "required": True},
    {"key": "timeout", "type": "int", "required": False}
]

Supported types:

• string - Text values
• int - Integer values
• bool - Boolean flags
• json - Complex JSON objects
• secret - Encrypted sensitive data

SDK Generation

Integrations can auto-generate Python SDKs from OpenAPI specs:

1. Provide an OpenAPI spec URL
2. Select authentication method (OAuth, API key, etc.)
3. Bifrost generates a typed Python client
4. Use the client in workflows with zero-config auth

# Generated SDK auto-authenticates via integration
from modules import example_api

result = await example_api.list_resources()  # Auth handled automatically

Access in Workflows

from bifrost import workflow, integrations
import httpx

@workflow
async def sync_data():
    # Get integration with merged config and OAuth
    integration = await integrations.get("ExternalAPI")

    if not integration:
        return {"error": "Integration not configured"}

    # Use OAuth token
    headers = {}
    if integration.oauth:
        headers["Authorization"] = f"Bearer {integration.oauth.access_token}"

    # Use config values
    base_url = integration.config.get("base_url")

    async with httpx.AsyncClient() as client:
        response = await client.get(f"{base_url}/data", headers=headers)
        return response.json()

Next Steps

• Creating Integrations - Setup guide
• SDK Generation - Generate API clients
• Integrations Module - SDK reference