Skip to main content

Asana authentication

This page documents the authentication and configuration options for the Asana agent connector.

Hosted mode (most cases)​

In hosted mode, create the connector through the Airbyte Agent CLI or API, then execute operations using the CLI, Python SDK, or API. If you need a step-by-step guide, see the developer quickstart.

OAuth​

Use the CLI for hosted OAuth connector creation when possible. It opens the hosted setup flow and avoids passing connector secrets through the command line:

airbyte-agent login
airbyte-agent connectors create --json '{
  "workspace": "<your_workspace_name>",
  "name": "asana"
}'

For API-first use cases, create a connector with OAuth credentials directly.

credentials fields you need:

Field NameTypeRequiredDescription
access_tokenstrNoOAuth access token for API requests
refresh_tokenstrYesOAuth refresh token for automatic token renewal
client_idstrNoConnected App Client ID
client_secretstrNoConnected App Client Secret

Example request:

curl -X POST "https://api.airbyte.ai/api/v1/integrations/connectors" \
  -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_name": "<WORKSPACE_NAME>",
    "connector_type": "Asana",
    "name": "My Asana Connector",
    "credentials": {
      "access_token": "<OAuth access token for API requests>",
      "refresh_token": "<OAuth refresh token for automatic token renewal>",
      "client_id": "<Connected App Client ID>",
      "client_secret": "<Connected App Client Secret>"
    }
  }'

Token​

Create a connector with Token credentials.

credentials fields you need:

Field NameTypeRequiredDescription
tokenstrYesYour Asana Personal Access Token. Generate one at https://app.asana.com/0/my-apps

Example request:

curl -X POST "https://api.airbyte.ai/api/v1/integrations/connectors" \
  -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_name": "<WORKSPACE_NAME>",
    "connector_type": "Asana",
    "name": "My Asana Connector",
    "credentials": {
      "token": "<Your Asana Personal Access Token. Generate one at https://app.asana.com/0/my-apps>"
    }
  }'

Execution​

After creating the connector, execute operations using the CLI, Python SDK, or API. If your Airbyte client can access multiple organizations, set the default organization with airbyte-agent organizations use, include organization_id in AirbyteAuthConfig, or include X-Organization-Id in raw API calls.

CLI

Authenticate with Airbyte:

airbyte-agent login

Create the connector. The CLI opens the hosted setup flow:

airbyte-agent connectors create --json '{
  "workspace": "<your_workspace_name>",
  "name": "asana"
}'

Describe the connector to see its supported entities and actions:

airbyte-agent connectors describe --json '{
  "workspace": "<your_workspace_name>",
  "name": "asana"
}'

Execute an action:

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "asana",
  "entity": "<entity>",
  "action": "<action>",
  "params": {}
}'

Python SDK

The connect() factory returns a fully typed AsanaConnector and reads AIRBYTE_CLIENT_ID / AIRBYTE_CLIENT_SECRET from the environment:

The recommended pattern is build_connector_tools, which gives the agent three tools bound to this connector: inspect_connector, read_skill_docs, and execute. The agent can inspect the connector, read only the skill-doc section it needs, and then execute:

inspect_connector() -> read_skill_docs() -> read_skill_docs(section="...") -> execute(entity, action, params)
Pydantic AI
from airbyte_agent_sdk import build_connector_tools
from pydantic_ai import Agent
from airbyte_agent_sdk import connect
from airbyte_agent_sdk.connectors.asana import AsanaConnector

connector = connect("asana", workspace_name="<your_workspace_name>")

tools = build_connector_tools(connector, framework="pydantic_ai")
agent = Agent("openai:gpt-4o", tools=tools.as_list())

Legacy alternatives​

These examples are kept for existing integrations. For new agents, use build_connector_tools above. The legacy AsanaConnector.tool_utils pattern loads the connector's full generated catalog into one broad execute tool description instead of letting the agent read skill docs on demand.

Pydantic AI
from pydantic_ai import Agent
from airbyte_agent_sdk import connect
from airbyte_agent_sdk.connectors.asana import AsanaConnector

connector = connect("asana", workspace_name="<your_workspace_name>")

agent = Agent("openai:gpt-4o")

@agent.tool_plain
@AsanaConnector.tool_utils
async def asana_execute(entity: str, action: str, params: dict | None = None):
    return await connector.execute(entity, action, params or {})

Or pass credentials explicitly (equivalent, useful when you're not loading them from the environment):

Pydantic AI
from airbyte_agent_sdk import build_connector_tools
from pydantic_ai import Agent
from airbyte_agent_sdk.connectors.asana import AsanaConnector
from airbyte_agent_sdk.types import AirbyteAuthConfig

connector = AsanaConnector(
    auth_config=AirbyteAuthConfig(
        workspace_name="<your_workspace_name>",
        organization_id="<your_organization_id>",  # Optional for multi-org clients
        airbyte_client_id="<your-client-id>",
        airbyte_client_secret="<your-client-secret>"
    )
)

tools = build_connector_tools(connector, framework="pydantic_ai")
agent = Agent("openai:gpt-4o", tools=tools.as_list())

API

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/connectors/<connector_id>/execute' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'X-Organization-Id: <YOUR_ORGANIZATION_ID>' \
  -H 'Content-Type: application/json' \
  -d '{"entity": "<entity>", "action": "<action>", "params": {}}'

Open source mode​

In open source mode, provide API credentials directly to the connector.

OAuth​

credentials fields you need:

Field NameTypeRequiredDescription
access_tokenstrNoOAuth access token for API requests
refresh_tokenstrYesOAuth refresh token for automatic token renewal
client_idstrNoConnected App Client ID
client_secretstrNoConnected App Client Secret

Example request:

from airbyte_agent_sdk.connectors.asana import AsanaConnector
from airbyte_agent_sdk.connectors.asana.models import AsanaOauth2AuthConfig

connector = AsanaConnector(
    auth_config=AsanaOauth2AuthConfig(
        access_token="<OAuth access token for API requests>",
        refresh_token="<OAuth refresh token for automatic token renewal>",
        client_id="<Connected App Client ID>",
        client_secret="<Connected App Client Secret>"
    )
)

Token​

credentials fields you need:

Field NameTypeRequiredDescription
tokenstrYesYour Asana Personal Access Token. Generate one at https://app.asana.com/0/my-apps

Example request:

from airbyte_agent_sdk.connectors.asana import AsanaConnector
from airbyte_agent_sdk.connectors.asana.models import AsanaPersonalAccessTokenAuthConfig

connector = AsanaConnector(
    auth_config=AsanaPersonalAccessTokenAuthConfig(
        token="<Your Asana Personal Access Token. Generate one at https://app.asana.com/0/my-apps>"
    )
)
Was this page helpful?