Asana
Use this page to set up the Asana source connector and find reference information.
Prerequisites
To use the Asana source connector, you need:
- An Asana account with access to the workspaces, projects, tasks, portfolios, and other resources you want to sync.
- One of these authentication methods:
- OAuth. Recommended for Airbyte Cloud. Airbyte Cloud manages the Asana OAuth app and token exchange for you. To configure OAuth yourself, register an Asana OAuth app and make it available in the authorising workspace. Enable Full permissions so the app accepts Asana’s
defaultOAuth scope. - Personal Access Token. Follow Asana’s personal access token instructions to create a token. To sync organization exports, use an Asana service account token.
- OAuth. Recommended for Airbyte Cloud. Airbyte Cloud manages the Asana OAuth app and token exchange for you. To configure OAuth yourself, register an Asana OAuth app and make it available in the authorising workspace. Enable Full permissions so the app accepts Asana’s
The connector only syncs data available to the authenticated Asana user. A view-only licence or limited project access applies the same restrictions to the connector.
Set up the connector
For Airbyte Cloud:
- Log into your Airbyte Cloud account.
- In the left navigation bar, click Sources.
- Click + New source.
- Select Asana from the available sources.
- Enter a Source name.
- Authenticate with OAuth or enter a personal access token.
- Optional: Enter Organization Export IDs to sync specific organization exports.
- Click Set up source.
For Airbyte Open Source:
- Go to the Airbyte Open Source dashboard.
- In the left navigation bar, click Sources.
- Click + New source.
- Select Asana from the available sources.
- Enter a Source name.
- Authenticate with OAuth or enter a personal access token.
- Optional: Enter Organization Export IDs to sync specific organization exports.
- Click Set up source.
Supported sync modes
The Asana source connector supports these sync modes:
| Feature | Supported? |
|---|---|
| Full Refresh Sync | Yes |
| Incremental Sync | No |
| Namespaces | No |
Supported streams
The Asana source connector supports these streams:
| Stream | Description |
|---|---|
attachments | Attachment details for attachments on synced projects and tasks. |
attachments_compact | Compact attachment records for synced projects and tasks. |
custom_fields | Custom field definitions in each accessible workspace. |
events | Events for synced projects and tasks. |
organization_exports | Organization export requests for the export IDs you provide in the source configuration. |
portfolio_items | Projects and portfolios contained in each synced portfolio. |
portfolios | Portfolio details for synced portfolios. |
portfolios_compact | Compact portfolio records for each synced workspace and user. |
portfolios_memberships | Portfolio memberships for synced portfolios. |
projects | Projects in each accessible workspace. |
sections | Section details for synced project sections. |
sections_compact | Compact section records for synced projects. |
stories | Story details for synced task stories. |
stories_compact | Compact story records for synced tasks. |
tags | Tags in each accessible workspace. |
tasks | Tasks in synced projects. |
team_memberships | Team membership records for synced teams. |
teams | Teams in each accessible organization workspace. |
users | Users in each accessible workspace. |
workspaces | Workspaces the authenticated user can access. |
Data type map
| Integration Type | Airbyte Type |
|---|---|
string | string |
int, float, number | number |
date | date |
datetime | datetime |
array | array |
object | object |
Limitations and troubleshooting
Expand to see details about Asana connector limitations and troubleshooting.
Connector limitations
Rate limits
Asana applies rate limits to each authorisation token. The standard limit is 150 requests per minute for free domains. Paid domains allow 1,500 requests per minute. The connector retries 429 Too Many Requests responses using Asana’s Retry-After header.
If rate limit errors continue, reduce the Number of concurrent threads in the source configuration.
Sync multiple projects
Airbyte syncs all Asana projects available to the authenticated user. You can’t filter the connector to specific projects.
Portfolio streams
The portfolios_compact, portfolios, portfolios_memberships, and portfolio_items streams depend on Asana portfolios. Portfolios aren’t available on every Asana plan. Without portfolios, Asana returns an HTTP 402 error, and these streams sync no records.
Organization exports
The organization_exports stream only syncs organization export IDs listed in the source configuration. First, create organization export requests in Asana. Then enter the returned export IDs in Organization Export IDs.
Asana’s organization export endpoints are only available to Enterprise organization service accounts. Authenticate with an Asana service account token to sync organization exports.
Troubleshooting
- If OAuth returns access errors, check that your Asana OAuth app is available in the authorising workspace. Also check that it’s configured with Full permissions. The connector requests Asana’s
defaultOAuth scope during authorisation. For more information, see Asana’s OAuth documentation. - For HTTP 402, 403, 404, 412, or 451 errors, the connector skips the request and continues syncing. It doesn’t fail the sync. If a stream returns fewer records than expected, check the authenticated Asana user’s access to those resources. If it returns no records, also check that your Asana plan includes the related feature.
- For other troubleshooting topics, see the Airbyte Forum.
IP allow list
If your organization restricts IP access, add the Airbyte Cloud IP addresses to your allow list when using Airbyte Cloud.
Reference
This connector uses the Asana REST API. All API requests use the https://app.asana.com/api/1.0 endpoint.
For OAuth, the connector includes Asana’s default OAuth scope in the authorisation request. For a custom Asana OAuth app, configure Full permissions so the app accepts the default scope.
For programmatic configuration, use these parameter names:
| Field | Required | Description |
|---|---|---|
credentials.option_title | Yes | Authentication method. Valid values are OAuth Credentials and PAT Credentials. |
credentials.client_id | Required for OAuth | Client ID for the Asana OAuth app. |
credentials.client_secret | Required for OAuth | Client secret for the Asana OAuth app. |
credentials.refresh_token | Required for OAuth | Refresh token returned by the Asana OAuth flow. |
credentials.personal_access_token | Required for personal access token authentication | Asana personal access token. For organization exports, use an Asana service account token. |
organization_export_ids | No | List of Asana organization export IDs to sync in the organization_exports stream. |
num_workers | No | Number of concurrent threads to use for the sync. Valid values are 1 through 25. Defaults to 10. |
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.8.0 | 2026-11-11 | 91313 | Migrate to manifest-only; restore support for legacy root-level access token configs and enable HTTP caching for parent streams. |
| 1.7.2 | 2026-05-22 | 78331 | Add default OAuth scope to consent URL |
| 1.7.1 | 2026-05-18 | 78159 | Remove explicit OAuth scopes from connector input specification |
| 1.7.0 | 2026-05-15 | 77577 | Add OAuth 2.0 support |
| 1.6.0 | 2026-05-14 | 78096 | Promoted release candidate to GA |
| 1.6.0-rc.2 | 2026-05-13 | 78082 | Fix projects stream HTTP 400 after CDK v7 upgrade |
| 1.6.0-rc.1 | 2026-04-23 | 76390 | Bump Airbyte CDK from ^6 to ^7.13.0 |
| 1.5.3 | 2026-04-13 | 76276 | Rename “concurrent workers” to “concurrent threads” in connector spec |
| 1.5.2 | 2026-04-07 | 76100 | Improve error messages for HTTP 400, 401, and 429 responses with granular failure type classification |
| 1.5.1 | 2025-12-09 | 70445 | Fix organization_export_ids spec to define array item types |
| 1.5.0 | 2025-05-05 | 59224 | Adds portfolio_items stream to sync items (such as projects and portfolios) in each portfolio (API reference) |
| 1.4.0 | 2025-04-24 | 58594 | Adds actual_time_minute field to the task stream |
| 1.3.10 | 2025-02-18 | 53891 | Update dependencies |
| 1.3.9 | 2025-02-08 | 53394 | Update dependencies |
| 1.3.8 | 2025-02-01 | 52882 | Update dependencies |
| 1.3.7 | 2025-01-25 | 52216 | Update dependencies |
| 1.3.6 | 2025-01-18 | 51750 | Update dependencies |
| 1.3.5 | 2025-01-11 | 51246 | Update dependencies |
| 1.3.4 | 2025-01-04 | 50915 | Update dependencies |
| 1.3.3 | 2024-12-28 | 50442 | Update dependencies |
| 1.3.2 | 2024-12-21 | 50195 | Update dependencies |
| 1.3.1 | 2024-12-14 | 48966 | Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64 |
| 1.3.0 | 2024-12-06 | 48712 | Upgrade to process full refresh and non-incremental substreams using concurrent CDK |
| 1.2.14 | 2024-11-04 | 48175 | Update dependencies |
| 1.2.13 | 2024-10-28 | 47026 | Update dependencies |
| 1.2.12 | 2024-10-12 | 46825 | Update dependencies |
| 1.2.11 | 2024-10-05 | 46501 | Update dependencies |
| 1.2.10 | 2024-09-28 | 46166 | Update dependencies |
| 1.2.9 | 2024-09-21 | 45754 | Update dependencies |
| 1.2.8 | 2024-09-14 | 45547 | Update dependencies |
| 1.2.7 | 2024-09-07 | 45277 | Update dependencies |
| 1.2.6 | 2024-08-31 | 44970 | Update dependencies |
| 1.2.5 | 2024-08-24 | 44722 | Update dependencies |
| 1.2.4 | 2024-08-17 | 44275 | Update dependencies |
| 1.2.3 | 2024-08-12 | 43807 | Update dependencies |
| 1.2.2 | 2024-08-10 | 43532 | Update dependencies |
| 1.2.1 | 2024-08-03 | 43079 | Update dependencies |
| 1.2.0 | 2024-07-27 | 42856 | Add task & target data to stories compact stream |
| 1.1.1 | 2024-07-27 | 42801 | Update dependencies |
| 1.1.0 | 2024-07-24 | 42488 | Add task data to stories stream |
| 1.0.9 | 2024-07-20 | 42144 | Update dependencies |
| 1.0.8 | 2024-07-13 | 41839 | Update dependencies |
| 1.0.7 | 2024-07-10 | 41573 | Update dependencies |
| 1.0.6 | 2024-07-09 | 41142 | Update dependencies |
| 1.0.5 | 2024-07-06 | 40865 | Update dependencies |
| 1.0.4 | 2024-06-25 | 40392 | Update dependencies |
| 1.0.3 | 2024-06-22 | 40092 | Update dependencies |
| 1.0.2 | 2024-06-18 | 39551 | Fix pagination from offset to cursor based, Increment airbyte_cdk to ^1 |
| 1.0.1 | 2024-06-06 | 39249 | [autopull] Upgrade base image to v1.2.2 |
| 1.0.0 | 2024-04-15 | 36697 | Migrate to low code |
| 0.6.1 | 2023-11-13 | 31110 | Fix hidden config access |
| 0.6.0 | 2023-11-03 | 31110 | Add new stream Portfolio Memberships with Parent Portfolio |
| 0.5.0 | 2023-10-30 | 31114 | Add Portfolios stream |
| 0.4.0 | 2023-10-24 | 31084 | Add StoriesCompact stream |
| 0.3.0 | 2023-10-24 | 31634 | Add OrganizationExports stream |
| 0.2.0 | 2023-10-17 | 31090 | Add Attachments stream |
| 0.1.9 | 2023-10-16 | 31089 | Add Events stream |
| 0.1.8 | 2023-10-16 | 31009 | Add SectionsCompact stream |
| 0.1.7 | 2023-05-29 | 26716 | Remove authSpecification from spec.json, use advancedAuth instead |
| 0.1.6 | 2023-05-26 | 26653 | Fix order of authentication methods |
| 0.1.5 | 2022-11-16 | 19561 | Added errors handling, updated SAT with new format |
| 0.1.4 | 2022-08-18 | 15749 | Add cache to project stream |
| 0.1.3 | 2021-10-06 | 6832 | Add oauth init flow parameters support |
| 0.1.2 | 2021-09-24 | 6402 | Fix SAT tests: update schemas and invalid_config.json file |
| 0.1.1 | 2021-06-09 | 3973 | Add entrypoint and bump version for connector |
| 0.1.0 | 2021-05-25 | 3510 | New Source: Asana |