2025 Growth Unified Hits Major Growth Milestones with 6.5x usage & 4.5x revenue growth
Unified.to
All articles

How to Integrate with Asana

February 26, 2026

An Asana API integration lets your product read and write tasks, projects, teams, users, and custom fields inside Asana workspaces. For SaaS companies building project management automation, reporting tools, or workflow integrations, that often means creating tasks, syncing project data, or triggering actions when work changes.

But a production-grade Asana integration involves more than generating a personal access token and calling /tasks. You need to implement authentication correctly, paginate large datasets, design around rate limits, and use webhooks instead of polling.

This guide covers:

  1. How to integrate directly with the Asana API
  2. The operational complexity you will own
  3. How to integrate Asana using Unified's Task and HR APIs
  4. When to build direct vs use an integration layer

If you're exploring how task management integrations fit into a broader integration strategy, see our overview of unified APIs for SaaS integrations.

Direct Asana API integration

Step 1: Understand the Asana API architecture

The Asana API is a REST interface with predictable resource-oriented URLs, JSON request bodies, and standard HTTP verbs. It supports create, read, update, and delete operations across objects like tasks, projects, and teams.

Asana's documentation explains the API structure and request format in its API quick start guide.

All endpoints are relative to the base API URL:

https://app.asana.com/api/1.0

For example:

POST /tasks

expands to:

https://app.asana.com/api/1.0/tasks

Requests can be JSON or form-encoded, and all responses are returned in JSON format.

Step 2: Authenticate your application

Asana supports several authentication methods.

Personal Access Tokens (PATs) are the quickest way to start using the API. PATs behave like long-lived API keys and inherit the permissions of the user who created them.

You can generate a PAT in the developer console as described in the personal access token documentation.

PATs are best suited for:

  • internal scripts
  • automation jobs
  • single-user integrations

For multi-user SaaS integrations, OAuth 2.0 is the recommended approach. OAuth allows each user to authorize your application without sharing credentials.

Asana's OAuth implementation is documented in the OAuth guide.

Step 3: Implement OAuth for multi-user integrations

OAuth follows the authorization code flow.

Your application redirects the user to:

https://app.asana.com/-/oauth_authorize

with parameters including:

  • client_id
  • redirect_uri
  • response_type=code
  • scope
  • state

After the user approves access, Asana redirects back with an authorization code.

You then exchange the code for tokens by sending a request to:

POST https://app.asana.com/-/oauth_token

The response includes:

  • access_token
  • refresh_token
  • expires_in

Access tokens typically expire after one hour. Refresh tokens are used to generate new access tokens when needed.

Full OAuth implementation details are documented in the authorization code grant documentation.

Step 4: Retrieve workspace information

Before creating tasks or projects, your application usually needs the workspace identifier.

To list workspaces:

GET /workspaces

This returns the workspaces available to the authenticated user.

To retrieve a specific workspace:

GET /workspaces/{workspace_gid}

Workspace APIs are described in the workspace API reference.

Step 5: Work with tasks and projects

The most common integration surface in Asana is the task resource.

Create a task:

POST /tasks

Example request:

{
  "data": {
    "workspace": "WORKSPACE_GID",
    "name": "Sample task",
    "assignee": "me"
  }
}

Retrieve a task:

GET /tasks/{task_gid}

Update a task:

PUT /tasks/{task_gid}

Delete a task:

DELETE /tasks/{task_gid}

These operations are documented in the Asana task API reference.

Projects organize tasks and support similar operations:

GET /projects
GET /projects/{project_gid}
POST /projects

See the projects API reference for full request parameters.

Step 6: Implement pagination

Large result sets must be paginated.

Asana supports pagination using:

  • limit
  • offset

Example:

GET /tasks?limit=50

Responses include a next_page object containing the offset token for the next page.

Asana strongly recommends paginating requests to avoid truncated results or timeouts.

Pagination behavior is documented in the pagination guide.

Step 7: Use webhooks instead of polling

Webhooks allow your integration to react to changes without repeatedly polling the API.

To create a webhook:

POST /webhooks

Required fields include:

  • resource (the resource being monitored)
  • target (your webhook endpoint)

Asana sends a handshake request with an X-Hook-Secret header, which your endpoint must return to complete verification.

Webhook behavior, retry logic, and limits are documented in the webhooks guide.

Step 8: Design around rate limits

Asana enforces both request and concurrency limits.

Typical request limits include:

  • 150 requests per minute for free domains
  • 1,500 requests per minute for paid domains

Concurrent request limits include:

  • 50 concurrent GET requests
  • 15 concurrent write requests

If limits are exceeded, the API returns:

429 Too Many Requests

along with a Retry-After header specifying how long to wait before retrying.

These limits are described in the rate limit documentation.

Where Asana integrations become operationally complex

A direct Asana integration means you own:

  • OAuth implementation and token refresh logic
  • workspace and user identity mapping
  • webhook lifecycle management and retries
  • pagination for large task and project datasets
  • rate-limit handling and concurrency control
  • custom field mapping and task metadata handling

For small automation scripts this is manageable.

For a multi-tenant SaaS product supporting many organizations, it becomes integration infrastructure.

Integrating Asana via Unified

Unified provides normalized APIs across task management platforms, including Asana.

Instead of integrating with Asana's API directly, you integrate with Unified's Task API and HR API.

Step 1: Register OAuth through Unified

When integrating through Unified, configure the OAuth redirect URI as:

https://api.unified.to/oauth/code

Regional variants are also available for EU and AU environments.

Users authorize their Asana account through Unified's authorization flow, and Unified returns a connection_id that identifies the connected account.

Step 2: Use normalized Unified objects

Based on the Asana coverage provided in Unified documentation, the integration supports normalized objects including:

  • Task
  • Task Project
  • Task Comment
  • HRIS Employee
  • HRIS Group
  • Custom field metadata

These objects normalize Asana resources such as:

  • tasks
  • projects
  • comments (stories)
  • users
  • teams

Step 3: Make your first Unified API calls

List projects:

GET /task/{connection_id}/project

List tasks in a project:

GET /task/{connection_id}/task?project_id={project_id}

Create a task:

POST /task/{connection_id}/task

Example payload:

{
  "name": "New task from Unified",
  "project_id": "PROJECT_ID",
  "notes": "Created via Unified API"
}

Update a task:

PUT /task/{connection_id}/task/{task_id}

List users:

GET /hris/{connection_id}/employee

List teams:

GET /hris/{connection_id}/group

Step 4: Use Unified webhooks

Unified supports both native and virtual webhook models.

  • Native webhooks use Asana's native webhook system.
  • Virtual webhooks simulate real-time events by polling the provider API and emitting events when changes occur.

This approach allows applications to receive normalized events such as:

  • task created
  • task updated
  • project updated

without implementing provider-specific webhook infrastructure.

Step 5: Use passthrough for unsupported endpoints

If an Asana endpoint is not covered by Unified's normalized model, you can use the passthrough API.

Passthrough supports:

  • GET
  • POST
  • PUT
  • DELETE

This allows direct calls to Asana's API while still using Unified's authentication and connection model.

Direct vs Unified: when to choose each

Build directly with Asana if:

  • Asana is a core feature of your product
  • you need full control over tasks, projects, teams, and custom fields
  • you want direct access to Asana's API capabilities

Use Unified if:

  • you plan to support multiple task management systems
  • you want one integration layer across providers
  • you want webhook handling abstracted
  • you want normalized objects across integrations

Final thoughts

Building a basic Asana integration is relatively straightforward.

Running a production integration across many organizations requires:

  • reliable authentication
  • webhook infrastructure
  • pagination strategies
  • rate-limit protection

If Asana is a core system for your customers, investing in a direct integration makes sense.

If task management is just one of many integrations your product needs, a unified API approach can significantly reduce engineering overhead and accelerate delivery.

→ Start your 30-day free trial

→ Book a demo

All articles