SDK Generation

Generate typed Python SDK clients from OpenAPI specifications with automatic authentication via integrations.

Overview

Bifrost can generate Python SDKs from OpenAPI specs that:

• Include typed data models from the spec
• Handle authentication automatically via integrations
• Provide retry logic with exponential backoff
• Support dot-notation for response access

Generate an SDK

1. Open your integration in Settings > Integrations

2. Click Generate SDK

3. Enter the OpenAPI Spec URL (JSON or YAML)

4. Select Authentication Type:

   • OAuth (uses integration OAuth tokens)
   • API Key (uses config value)
   • Basic Auth (uses config values)
   • Bearer Token (uses config value)

5. Click Generate

6. SDK is created in your workspace at modules/{name}.py

Using Generated SDKs

Generated SDKs auto-authenticate using your integration:

from modules import example_api

@workflow
async def fetch_data():
    # No auth setup needed - uses integration automatically
    resources = await example_api.list_resources()
    return {"count": len(resources)}

Authentication Types

OAuth

Uses OAuth tokens from the integration:

# Generated SDK fetches token from integration.oauth.access_token
result = await api.get_users()

API Key

Uses api_key from integration config:

# Generated SDK adds header: X-API-Key: {config.api_key}
result = await api.get_users()

Bearer Token

Uses token from integration config:

# Generated SDK adds header: Authorization: Bearer {config.token}
result = await api.get_users()

Basic Auth

Uses username and password from integration config:

# Generated SDK uses HTTP Basic auth
result = await api.get_users()

Response Access

Generated SDKs support dot-notation for responses:

# Instead of result["data"]["user"]["name"]
print(result.data.user.name)

# Also works as dict
print(result["data"]["user"]["name"])

Retry Logic

Generated SDKs include automatic retry:

• Retries on 429 (rate limit) and 5xx errors
• Exponential backoff with jitter
• Respects Retry-After headers
• Configurable max retries

Generated Code Structure

modules/example_api.py

# Data models from OpenAPI schemas
class User:
    id: str
    name: str
    email: str

    @classmethod
    def from_dict(cls, data: dict) -> "User":
        ...

# Internal HTTP client
class _ExampleApiClient:
    def __init__(self, base_url: str, session: httpx.AsyncClient):
        ...

    async def list_users(self) -> list[User]:
        ...

# Lazy client that auto-initializes from integration
_lazy_client = _LazyClient()

# Module-level functions
async def list_users() -> list[User]:
    return await _lazy_client.list_users()

Requirements

The OpenAPI spec should include:

• servers[0].url - Base URL (or configured in integration)
• paths - Endpoint definitions
• components.schemas - Data models (optional)
• security - Authentication requirements (optional)

Regenerating SDKs

To update an SDK after spec changes:

1. Open the integration
2. Click Regenerate SDK
3. The module file is overwritten with new code

Caution

Regenerating overwrites any manual changes to the SDK file.

Example: HaloPSA

from modules import halopsa

@workflow
async def sync_tickets():
    # Auto-authenticated via HaloPSA integration
    tickets = await halopsa.list_tickets()

    for ticket in tickets:
        print(f"{ticket.id}: {ticket.summary}")

    return {"synced": len(tickets)}

Next Steps

• Creating Integrations - Setup guide
• Integrations Module - SDK reference