Creating Integrations

Create integrations to connect Bifrost to external APIs with OAuth and configuration management.

Create an Integration

1. Navigate to Settings > Integrations

2. Click Create Integration

3. Fill in basic details:

   • Name: Unique identifier (e.g., “Microsoft_Graph”, “HaloPSA”)
   • Description: What this integration connects to

4. Configure the Config Schema (optional):

   • Add fields like base_url, api_key, tenant_id
   • Set types: string, int, bool, json, or secret

5. Link an OAuth Provider (optional):

   • Select existing OAuth connection
   • Or configure custom OAuth settings

6. Save the integration

Set Integration Defaults

Configure default values that apply to all organizations:

1. Open the integration

2. Go to Configuration tab

3. Fill in default values:

   • Base URLs
   • Default timeouts
   • Shared API keys

4. Save

Tip

Secrets are encrypted at rest. Use the secret type for API keys and tokens.

Create Organization Mappings

Map each organization to its external entity:

1. In the integration, go to Mappings tab

2. Click Add Mapping

3. Select the Organization

4. Set the Entity ID (tenant ID, company ID, etc.)

5. Override any config values specific to this org

6. Optionally link an org-specific OAuth token

7. Save

OAuth Configuration

Link Existing OAuth Provider

If you already have an OAuth connection:

1. In integration settings, select OAuth Provider
2. Choose from existing connections
3. Tokens are automatically available via integration.oauth

Configure OAuth Inline

For new OAuth connections:

1. In integration OAuth settings, configure:

   • Authorization URL
   • Token URL
   • Client ID/Secret
   • Scopes

2. Click Connect to authorize

Config Schema Types

Type	Description	Example
string	Text value	Base URL
int	Integer	Timeout seconds
bool	True/False	Enable feature flag
json	Complex object	Custom settings
secret	Encrypted	API keys, tokens

Use in Workflows

from bifrost import workflow, integrations
import httpx

@workflow
async def fetch_customers():
    # Get integration
    integration = await integrations.get("HaloPSA")
    if not integration:
        return {"error": "Integration not configured"}

    # Access config
    base_url = integration.config.get("base_url")
    tenant = integration.entity_id

    # Access OAuth token
    token = integration.oauth.access_token if integration.oauth else None

    # Make API call
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"{base_url}/api/customers",
            headers={
                "Authorization": f"Bearer {token}",
                "X-Tenant-ID": tenant
            }
        )
        return response.json()

Multi-Tenant Pattern

For APIs that serve multiple tenants:

1. Create one integration (e.g., “HaloPSA”)

2. Set Entity ID Name (e.g., “Tenant ID”)

3. Create mappings for each organization with their tenant ID

4. In workflows, integration.entity_id returns the correct tenant

# Each org gets their own tenant automatically
integration = await integrations.get("HaloPSA")
tenant_id = integration.entity_id  # Org-specific

Next Steps

• SDK Generation - Generate API clients
• Integrations Module - SDK reference