Manage workspaces

FreeIndividualTeamCustom Compare plans

A workspace is a container inside your Airbyte Agents organization that holds a set of connectors and credentials. A token scoped to one workspace can't reach another.

Most apps use the default workspace and never think about this again. The Workspace class and connect() both default to workspace_name="default". Reach for multiple workspaces only when you actively need to isolate credentials across distinct tenants, teams, or environments.

Use a specific workspace

To target a workspace other than default, pass workspace_name. Use a stable identifier that makes sense in your app, such as an internal tenant ID or team slug.

agent.py

import asyncio
from airbyte_agent_sdk import Workspace

async def main():
    async with Workspace(workspace_name="acme_corp") as ws:
        connectors = await ws.list_connectors()
        print(connectors)

asyncio.run(main())

connect() accepts the same argument.

agent.py

from airbyte_agent_sdk import connect

stripe = connect("stripe", workspace_name="acme_corp")

async with vs direct construction

Workspace can be used as an async context manager or constructed directly. The context manager form is recommended because it closes the underlying HTTP client when the block exits. If you construct a Workspace directly, call await ws.close() yourself when you're done with it.

agent.py

# Preferred: automatic cleanup
async with Workspace() as ws:
    connectors = await ws.list_connectors()

# Also valid: you own the lifecycle
ws = Workspace()
try:
    connectors = await ws.list_connectors()
finally:
    await ws.close()

Auto-creation

You don't explicitly create a workspace. Airbyte provisions one automatically the first time you mint a scoped or widget token for a new workspace_name (see Authentication on the API side). Under the hood, Workspace() and connect() both mint a scoped token on first use, so opening a Workspace is enough.

list_connectors() and get_connector() against a workspace_name that hasn't been created yet raise httpx.HTTPStatusError with a 404 status. They don't return an empty list and they don't implicitly create the workspace. If you want to start from a known-empty workspace, catch the 404:

agent.py

import httpx
from airbyte_agent_sdk import Workspace

async with Workspace(workspace_name="tenant-123") as ws:
    try:
        connectors = await ws.list_connectors()
    except httpx.HTTPStatusError as err:
        if err.response.status_code == 404:
            connectors = []
        else:
            raise

Operations that require the API

The SDK doesn't expose every workspace operation. If you need to do any of the following, use the API instead:

• List every workspace in your organization.
• Update a workspace's status, for example to deactivate one.
• Delete a workspace and its data.
• Read a workspace's metadata, like ID, status, or created_at, without opening it.