> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asana

> Integration details and setup guide for the Asana connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens) or Personal Access Token (Bearer) |
| **Two-Way Sync**                    | Yes                                                                                  |
| **Events Supported**                | Yes (Webhooks)                                                                       |
| **Realtime**                        | Yes                                                                                  |
| **Supports Rate Limiting**          | Yes (150 requests per minute)                                                        |
| **Authentication Scopes Supported** | `default` (provides access to all resources)                                         |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Asana**:

* **Access Requests**
* **Allocations**
* **Attachments**
* **Audit Log API**
* **Batch API**
* **Custom Field Settings**
* **Custom Fields**
* **Custom Types**
* **Events**
* **Exports**
* **Goal Relationships**
* **Goals**
* **Jobs**
* **Memberships**
* **Messages**
* **Organization Exports**
* **Portfolios**
* **Portfolio Memberships**
* **Project Briefs**
* **Project Memberships**
* **Project Statuses**
* **Project Templates**
* **Projects**
* **Rules**
* **Sections**
* **SSPM**
* **Status Updates**
* **Stories**
* **Tags**
* **Task Templates**
* **Tasks**
* **Team Memberships**
* **Teams**
* **Time Periods**
* **Time Tracking Entries**
* **Typeahead**
* **User Task Lists**
* **Users**
* **Webhooks**
* **Workspace Memberships**
* **Workspaces**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Asana offers a free Basic plan with limited features. Sign up at [https://asana.com](https://asana.com) to test the integration. |
| **Requires requires paid sandbox**                 | No paid sandbox required.                                                                                                             |
| **Requires partnership to obtain authentication?** | No. OAuth 2.0 credentials and Personal Access Tokens can be obtained directly through your Asana account settings.                    |

***

### Authentication (OAuth 2.0 or Personal Access Token)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

#### Option 1: OAuth 2.0 (Recommended for user-facing integrations)

1. Go to **Asana Developer Console** ([https://app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)) and click **Create new app**.
2. Fill in your app details:
   * **App Name**: A descriptive name for your integration
   * **App URL**: Your application's website
   * **Redirect URL**: [https://api.runalloy.com/api/strategy/connector/asana/callback](https://api.runalloy.com/api/strategy/connector/asana/callback)
3. Once created, navigate to the **OAuth** section of your app.
4. Copy your **Client ID** and **Client Secret**.
5. Enter your **Client ID** and **Client Secret** into Alloy Automation.

#### Option 2: Personal Access Token (PAT)

1. Log in to your **Asana account** and go to **My Settings**.
2. Navigate to the **Apps** tab and scroll to **Personal Access Tokens**.
3. Click **Create new token**, provide a description, and click **Create token**.
4. Copy the generated Personal Access Token (you won't be able to see it again).
5. Enter the token into Alloy Automation as a Bearer token.

#### Scopes

Asana uses a simplified scope model where the `default` scope provides access to all resources the authenticating user can access. Access is automatically limited by the user's permissions within Asana workspaces and projects.

***

## Use Cases

### 1) Project and task synchronization

Sync projects, tasks, and subtasks between Asana and other project management tools or issue trackers, ensuring teams stay aligned across multiple platforms without manual updates.

### 2) Automated task creation from external events

Automatically create Asana tasks when specific events occur in other systems—such as customer support tickets, form submissions, or pipeline stage changes—streamlining workflow automation.

### 3) Time tracking and resource management

Integrate Asana's time tracking entries with timesheets, billing systems, or resource planning tools to provide comprehensive visibility into team capacity and project budgets.

### 4) Custom field data enrichment

Sync custom field data between Asana and other business systems, enabling consistent data models across platforms and advanced reporting based on custom attributes.

### 5) Portfolio and goal tracking

Pull portfolio and goal data from Asana into business intelligence tools or executive dashboards, providing leadership with real-time visibility into strategic initiatives and OKR progress.

***

## API Gotchas

* ⚠️ **Rate limiting:** Asana enforces a rate limit of 150 requests per minute per access token. The API uses a cost-based system where different endpoints have different costs.
* ⚠️ **Pagination:** Asana uses cursor-based pagination. Always use the `offset` token from the response to fetch the next page rather than implementing page number-based pagination.
* ⚠️ **Webhook handshake:** When creating webhooks, Asana sends a handshake request that must be responded to with a 200 status and the `X-Hook-Secret` header value within 10 seconds.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.