Overview

Helpful code snippets will show up in this column.

curl https://app.asana.com/api/1.0/users/me \
  -H "Authorization: Bearer 0/a7f89e98g007e0s07da763a"

const asana = require('asana');

<?php
require 'php-asana/vendor/autoload.php';

import asana

import com.asana.*;

require 'asana'

The Asana API is a RESTful interface, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate from a wide variety of environments: command-line utilities, gadgets, and even the browser URL bar itself.

The API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. Only UTF-8 character encoding is supported for both requests and responses.

For quick access to REST API resources and object schemas, see:

• API reference
• Schemas

Object hierarchy

Asana is a work tracking and collaboration tool. This guide is designed to give developers a brief overview of how Asana is structured. It is not meant to be exhaustive, as the intention is to describe the fundamental elements of Asana to help you scope apps and avoid common points of confusion.

How work is organized

Tasks

Tasks are the basic unit of action in Asana. Tasks have many fields including a single assignee, name, notes, followers (i.e., collaborators), likes, and comments (among others). Tasks inherit custom fields from their parent project(s). Custom fields values are set for each individual task.

In addition to standard Create / Read / Update / Delete operations, there are a few things to watch out for when working with tasks:

1. Tasks can be orphaned and belong to no projects, they can belong to one project, or they can be multi-homed across two or more projects. The memberships field is a collection of the projects with which the task is associated.
   
2. Tasks can be multi-homed as subtasks. For example, task A can be in project B and the same task A can also be a subtask of task C.

• Tasks API documentation
• Tasks in the Asana product guide

Projects

A project is a collection of tasks that can be viewed as a list, board, timeline, and calendar. Projects can only exist in a single organization or workplace and only belong to a single team. Projects can be public in the team or private to project members. Among the many fields associated with projects, they can have global (shared across the organization) or local (project-specific) custom fields. A project’s custom fields will be displayed on each task within the project.

• Projects API documentation
• Projects in the Asana product guide

Portfolios

Portfolios are collections of projects (or other portfolios). Custom fields can be added to portfolios in addition to standard fields that are displayed on every portfolio. These fields provide a high-level overview of the status of each project within the portfolio.

• Portfolios API documentation
• Portfolios in the Asana product guide

Sections

A section is a group of tasks within a project. Sections let you divide tasks into categories, workflow stages, priorities, and more.

• Sections API documentation
• Sections in the Asana product guide

Subtasks

A subtask is exactly the same as tasks in a project, except that one (and only one) of its parents is a task (although subtasks can also simultaneously be organized into projects). To check if a task has a subtask, include the num_subtasks field when fetching the parent task.

Things to note when working with subtasks:

1. Subtasks do not inherit the projects of their parent tasks.
   
2. There can be up to 5 levels of subtasks below a task. We do not recommend making sub-subtasks.
3. There is no way to fetch all subtasks of all tasks in a project in a single request.

• Subtasks API documentation
• Subtasks in the Asana product guide

How users are organized

Workspaces

A workspace is the highest-level organizational unit in Asana. All projects, tasks, and teams have an associated workspace.

• Workspace / organization API documentation
• Workspaces in the Asana product guide

Organizations

An organization is a special kind of workspace that represents a company. Organizations connect all the employees at a company using Asana in a single space based on the company’s shared email domain. In an organization, you can group your projects into teams.

• Workspace / organization API documentation
• Organizations in the Asana Product Guide

Teams

Teams are a subset of users in an organization who collaborate on projects together. Every project in an organization is associated with one team. Team messages are not currently available in the API.

• Teams API documentation
• Teams in the Asana product guide

Users

A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. Asana accounts are free and tied to individuals; Asana accounts grant access to one or more shared workspaces and organizations to collaborate with other Asana users.

• Users API documentation
• Users & guests in the Asana product guide

Guest users

Users can invite clients, contractors, customers, or anyone else who does not have an email address at an approved organization email domain. These users join as organization guests. Guests have limited access in an organization. That is, guests can only see what is explicitly shared with them.

Note: it can be advantageous to use guests to create "bot" accounts. Due to the access restrictions, bots created from a guest account personal access token can be given fine-grained access to only the data that it needs to use.

• Users API documentation
• Users & guests in the Asana prodouct guide

News and changelog

To keep up to date on changes to the API, subscribe to Platform News in our developer forum.

To subscribe to updates:

1. Go to Platform News.
2. Select Log In in the top right and log in with your Asana account.
3. Go back to Platform News and change the bell icon in the top right to "Watching First Post" or "Tracking".

Here are the most recent updates:

• Upcoming changes that impact team management 2022-10-19 17:28:15.050
• Changes to Goal Metrics progress sources 2022-10-14 17:48:56.858
• New App Gallery & App Listings 2022-10-05 23:25:18.588
• API News 2022-W39 2022-09-29 20:56:03.578
• API Changelog 2022-09-29 20:54:14.026

Input/output options

GET URL params

?opt_pretty
?opt_fields=followers,assignee

PUT or POST body options

options: { 
  pretty: true,
  fields: ["followers", "assignee"]
}

In addition to providing fields and their values in a request, you may also specify options to control how your request is interpreted and how the response is generated.

For GET requests, options are specified as URL parameters prefixed with opt_. For POST or PUT requests, options are specified in the body.

If the body uses the application/x-www-form-urlencoded content type, then options are prefixed with opt_ just like for GET requests. If the body uses the application/json content type, then options are specified inside the top-level options object (a sibling of the data object).

?opt_fields=name,notes&opt_pretty response

HTTP/1.1 200
{
  "data": {
    "name": "Make a list",
    "notes": "Check it twice!",
    "gid": 1224
  }
}

These options can be used in combination in a single request, though some of them may conflict in their impact on the response.

Selecting fields

opt_fields nesting

"data": {                       < this
  "gid": 1001,
  "name": "Feed the cat",       < this.name
  "workspace": {                < this.workspace
    "gid": 14916,
    "name": "Shared Projects",  < this.workspace.name
  },
  "followers": [{               < this.followers
    "gid": 1234,
    "email": "tbizarro@…",      < this.followers.email
  }, {
    "gid": 5678,
    "email": "gsanchez@…",      < this.followers.email
  }]
}

Some output options allow you to reference fields of objects to include in the response. The way to specify a field is by path. A path is made up of a sequence of terms separated by the dot (.) operator. It takes the form this.a.b… where this refers to an object returned at the top level of the response, a the name of a field on a root object, b a field on a child object referred to by a, and so on.

For example, when retrieving a task or tasks, the path this.followers.email refers to the email field of all users mentioned in the followers field of the task or tasks returned (see the annotated output on the right).

There are also some advanced operators you can use for shorter syntax in selecting fields:

( .. | .. )

The group operator can be used in place of any whole term in a path, and will match any of a group of terms. For example:

this.(followers|assignee).email will match the email field of the assignee object or any of the followers.

Pagination

Paginating requests for object sets that may be large is highly recommended. For requests that will return large result sets, the API may truncate the result or timeout attempting to gather the data. Pagination ensures a more reliable experience by limiting requests to a smaller number of objects at a time, ultimately getting you the results faster. Should there be more results, the API will return an offset that will allow you to access the next page.

Strongly prefer paginated requests

For all new features in the Asana API, we're making pagination required by specifying a value for the limit parameter. Though they may return more results, our current unpaginated requests are still ultimately subject to a timeout limit, which means requests that work successfully one day may fail later due to factors such as server load and network latency.

Pagination limits provide a mechanism to specify a page size that we should always be able to serve regardless of these factors. To prevent current integrations from breaking, pagination is not enabled by default on "grandfathered" endpoints; instead, you can request paginated results by providing the optional limit parameter in your query. We will be working to deprecate requests to these endpoints in the future.

Request

curl "https://app.asana.com/api/1.0/tasks?project=1337&limit=5&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" \
  -H "Authorization: Bearer <personal_access_token>"

Response

{
  "data": [
    {
      "id": 1000,
      "name": "Task 1",
      ...
    },
    ...
  ],
  "next_page": {
    "offset": "yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9",
    "path": "/tasks?project=1337&limit=5&offset=yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9",
    "uri": "https://app.asana.com/api/1.0/tasks?project=1337&limit=5&offset=yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9"
  }
}

Note that all of Asana's official client libraries support pagination by default.

When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.

When making paginated requests, you are able to "page through" all objects for a particular query up to 100 objects at a time. Alternatively, your query will be truncated at about 1,000 objects. In addition, when issuing non-paginated requests to organizations with a large number of objects, queries may time out before returning. For these reasons, we recommend that you paginate all requests to the API.

This method returns paginated results for tasks from a project.

Errors

Missing authorization header

GET https://app.asana.com/api/1.0/users/me HTTP/1.1

HTTP/1.1 401 Not Authorized
{
  "errors": [
  {
    "message": "Not Authorized"
  }
  ]
}

HTTP status codes

Unfortunately, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP response status code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.

In the event of a server error, the response body will contain an error phrase. These phrases are automatically generated using the node-asana-phrase library and can be used by Asana support to quickly look up the incident that caused the server error.

Bad request parameters

GET https://app.asana.com/api/1.0/tasks HTTP/1.1
Authorization: Bearer <personal_access_token>

HTTP/1.1 400 Bad Request
{
  "errors": [
  {
    "message": "workspace: Missing input"
  }
  ]
}

Asana had a problem

GET https://app.asana.com/api/1.0/users/me HTTP/1.1
Authorization: Bearer <personal_access_token>

HTTP/1.1 500 Server Error
{
  "errors": [
  {
    "message": "Server Error",
    "phrase": "6 sad squid snuggle softly"
  }
  ]
}

In the event of an error, the response body will contain an errors field at the top level. This contains an array of at least one error object, described below:

API limits

API queries that run on very large result sets – on the order of tens of thousands of items – may have their results truncated even when you use pagination, use a filter on dates, or you don’t have access to all of those objects.

If your query hits this limit – on the last page of results, the API will respond with a 400 error rather than returning additional data. The 400 error will include a message that indicates a truncated data set.

Note that this limit concerns objects of all resource types (projects, tasks, teams, etc.). This limit also applies to:

• Result sets generated by a single (i.e., canonical) API request (e.g., GET /projects to fetch all projects in a workspace), prior to pagination, and following the application of any query filters provided in the request
• Result sets that would otherwise return a very large number of objects, but you only have access to a subset of them (e.g., guest permissions)

Workarounds

To help you retrieve these very large data sets, there are a number of workaround solutions you can take.

Split API requests

In most cases, you can break down your query into multiple canonical requests based on the hierarchical structure of the object you’re querying. For example:

• Instead of retrieving all projects in a workspace at once, you can:
  1. Retrieve all teams in a workspace, then
  2. Retrieve all projects for each of those teams in multiple queries
• Instead of retrieving all tasks in a project at once, you can:
  1. Retrieve all sections in a project, then
  2. Retrieve all tasks in each of those sections in multiple queries

Export data

If you are unable to use other methods and need an automated export, you can request data using an organization export. This feature is only available to Service Accounts of an Enterprise organization.

Additionally, admins can export subsets of organization data as CSV, such as tasks in a project.

Rate limits

To protect the stability of the API and keep it available to all users, Asana enforces multiple kinds of rate limiting. Requests that hit any of our rate limits will receive a 429 Too Many Requests response, which contains the standard Retry-After header indicating how many seconds the client should wait before retrying the request.

Limits are allocated per authorization token. Different tokens will have independent limits.

The client libraries respect the rate-limited responses and will wait the appropriate amount of time before automatically retrying the request, up to a configurable maximum number of retries.

Standard rate limits

Request

GET https://app.asana.com/api/1.0/users/me HTTP/1.1
Authorization: Bearer <personal_access_token>

Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30

{
  "errors": [
  {
    "message": "You've made too many requests and hit a rate limit. Please retry after the given amount of time."
  }
  ]
}

Our standard rate limiter imposes a quota on how many requests can be made in a given window of time. Our limits are based on minute-long windows, and differ depending on whether the domain is premium or not. We may change these quotas or add new quotas (such as maximum requests per hour) in the future.

In addition, calls to the search API are limited to 60 requests per minute. The duplication endpoints are limited to 5 concurrent jobs.

Although the quota is defined per minute, it is evaluated more frequently than once per minute. As such, you may not need to wait for a full minute before retrying your request. For requests rejected by this limiter, the Retry-After header has the result of this calculation.

Requests rejected by this limiter still count against the quotas, so that ignoring the Retry-After header will result in fewer and fewer requests being accepted during the subsequent time windows.

Concurrent request limits

In addition to limiting the total number of requests in a given time window, we also limit the number of requests being handled at any given instant. We may change these limits or add new limits in the future.

For example, if you have 50 read requests in-flight and attempt to make another read request, the API will return a 429 Too Many Requests error. The read and write limits are independent of each other, so the number of read requests you make at one time will have no impact on the number of write requests you can make.

Responses for requests rejected by this concurrent request limiter will contain a Retry-After header, which specifies a duration long enough (in seconds) such that the other in-flight requests are guaranteed to have either completed or timed out.

Cost limits

Objects in Asana are connected to each other in a graph. Some examples of "links" in this graph are:

• A task object is linked to a user object as the assignee
• A user is linked to the projects it is following
• A tag is linked to all its tasks
• A task is linked to all its subtasks
• A task is linked to all its custom field values

Depending on the kind of requests you make to our API, our servers traverse different parts of the graph. The sizes of these parts directly influence how expensive it is for our servers to build the API responses. For example, fetching just the name and gid of a task requires very few resources and no traversal of the graph, but fetching all tasks in a project and all their attributes (assignee, followers, custom_fields, likes) can require following several thousand links in the graph.

Because there can be a wide range in the cost of any given API request in terms of the computational resources and database load, the standard rate limits are not always enough to maintain stability of the API. In the past, when we’ve received bursts of expensive requests, our typical course of action has been to block the offending authorization token and reject all future requests, resulting in confusion for both the user and the app developer. Instead, to protect against the extreme cases where API requests require inordinate traversal of the graph, we impose an additional limit based on the computational cost.

The cost we associate with a request isn't equivalent to the number of links in the subset of the graph involved, but it is roughly proportional. The cost of a request is calculated after the response has been fully built and we know how much data we needed to fetch from our databases to build it. This cost is then deducted from a quota, and the response is returned. Because the cost of a request is not known until we’ve built the response, we allow this deduction to result in a net negative quota. The request that causes the quota to become negative will receive the expected response and not be rejected.

When a request is received, if the remaining quota is not positive, the new request is rejected with a 429 Too Many Requests. As with the standard rate limits, this quota is defined per-minute but is updated on a more frequent interval. The Retry-After header will specify how long you must wait for the quota to become positive again.

The vast majority of developers will be unaffected by the cost limit, and the quota is set sufficiently high that it only affects users making requests that would compromise the stability of the API. Rather than unconditionally blocking their token from the API, this cost limiter will permit them to continue operation at a slower but safe and stable rate.

Common issues and pathological cases to avoid

• Deeply nested subtasks (i.e., working sub-subtasks, sub-sub-subtasks, etc.)
• Projects with a large number of tasks (i.e, projects with over 1,000 tasks)
• Too many unreadable tags in a workspace
• Domains with too many projects for typeahead to work well
• Undeleted webhooks

Rich text

Note: We are actively adding new rich texts formats to various objects in Asana. This may break existing apps. New apps should be built using parsers and display logic that is forward compatible with the forthcoming rich text formats. More details and ongoing updates can be found in this post in the developer forum.

Example rich text

<body>All these new tasks are <em>really</em> getting disorganized, so <a data-asana-gid="4168112"/> just made the new <a data-asana-gid="5732985"/> project to help keep them organized. <strong>Everyone</strong> should start using the <a data-asana-gid="6489418" data-asana-project="5732985"/> when adding new tasks there.</body>

The web product offers a number of rich formatting features when writing task notes, comments, project descriptions, and project status updates. These features include bold, italic, underlined, and monospaced text, as well as bulleted and numbered lists. Additionally, users can "@-mention" other users, tasks, projects, and many other objects within Asana to create links.

The rich text field name for an object is equivalent to its plain text field name prefixed with html_. The following object types in Asana support rich text:

Reading rich text

Python

from lxml import etree

html_text = "<body>...</body>"
root = etree.HTML(html_text)
user_ids = root.xpath('//a[@data-asana-type="user"]/@data-asana-gid')
for user_id in user_ids:
    print(user_id)

Java

import com.jcabi.xml.XML;
import com.jcabi.xml.XMLDocument;
import java.util.List;

XML root = new XMLDocument("<body>...</body>");
List<String> userIds = root.xpath("//a[@data-asana-type=\"user\"]/@data-asana-gid");
for (String userId : userIds) {
    System.out.println(userId);
}

JavaScript

var htmlText = '<body>...</body>'
var parser = new DOMParser()
var doc = parser.parseFromString(htmlText, "text/html")
var iterator = doc.evaluate(
    '//a[@data-asana-type="user"]/@data-asana-gid', doc, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE)
var node = iterator.iterateNext()
while (node) {
    console.log(node.nodeValue);
    node = iterator.iterateNext();
}

Rich text in the API is formatted as an HTML fragment, which is wrapped in a root <body> tag. Rich text is guaranteed to be valid XML; there will always be a root element, all tags will be closed, balanced, and case-sensitive, and all attribute values will be quoted. The following is a list of all the tags that are currently returned by the API:

In addition, the following tags are supported in the rich text of only some objects:

Note: The above lists will expand as new features are introduced to the Asana web product. Treat rich text as you would treat arbitrary HTML, and ensure that your code does not break when it encounters a tag not on this list.

Links

While links are intuitive to understand when users view the rendered result in the Asana web product, an <a> tag and its href alone are insufficient to programmatically understand what the target of the link is. This is confused further by the fact that the formats of these links are frequently ambiguous. For example, an @-mention to a user generates a link to their "My Tasks", which looks identical to a link to a normal project.

Because of this, the API will return additional attributes in <a> tags to convey meaningful information about the target. The following is a complete list of attributes we may return inside an <a> tag, in addition to the usual href:

	Attribute	Meaning
	data-asana-accessible	Boolean, representing whether or not the linked object is accessible to the current user. If the resource is inaccessible, no other data-asana-* attributes will be included in the tag.
	data-asana-dynamic	Boolean, represents if contents of the a tag is the canonical name of the object in Asana. If you want to set custom text that links to an Asana object, set data-asana-dynamic="false" when creating the tag.
	data-asana-type	The type of the referenced object. One of user, task, project, tag, conversation, project_status, team, or search.
	data-asana-gid	The GID of the referenced object. If the referenced object is a user, this is the user's GID.
	data-asana-project	If the type of the referenced object is a task, and the link references that task in a particular project, this is the GID of that project.
	data-asana-tag	If the type of the referenced object is a task, and the link references that task in a particular tag, this is the GID of that tag.

Here are some examples of how this behavior manifests:

• Suppose a user with a name of "Tim" and a user GID of "53421" is @-mentioned. This will create a link to their "My Tasks" which is a project with a GID of "56789"
  • The raw link generated in Asana will be https://app.asana.com/0/56789/list.
  • The <a> tag returned in the API will be <a href="https://app.asana.com/0/56789/list" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="user" data-asana-gid="54321">@Tim</a>.
• Suppose a link to a task with name "Buy milk" and GID "1234" being viewed in a project with GID "5678" is copied from the address bar and pasted into a comment.
  • The raw link generated in Asana will be https://app.asana.com/0/5678/1234.
  • The <a> tag returned in the API will be <a href="https://app.asana.com/0/5678/1234" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="task" data-asana-gid="1234" data-asana-project="5678">Buy milk</a>
• Suppose another user @-mentions a project with GID "5678" that is private and not visible to you in the web product.
  • The raw link generated in Asana will be https://app.asana.com/0/5678/list.
  • The <a> tag returned in the API will be <a href="https://app.asana.com/0/5678/list" data-asana-accessible="false" data-asana-dynamic="true">Private Link</a>

Here is an example of what a complete rich comment might look like in the API:

<body>All these new tasks are <em>really</em> getting disorganized, so <a href="https://app.asana.com/0/4168466/list" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="user" data-asana-gid="4168112">@Tim Bizzaro</a> just made the new <a href="https://app.asana.com/0/5732985/list" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="project" data-asana-gid="5732985">Work Requests</a> project to help keep them organized. <strong>Everyone</strong> should start using the <a href="https://app.asana.com/0/5732985/6489418" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="task" data-asana-gid="6489418" data-asana-project="5732985">Request template</a> when adding new tasks there.</body>

Inline images

Reading an inline image

<img
  data-asana-gid="1234"
  src="..."
  data-src-width="..."
  data-src-height="..."
  data-thumbnail-url="..."
  data-thumbnail-width="..."
  data-thumbnail-height="..."
  [data-asana-deleted="true"]
  data-asana-type="attachment"
  alt="title of the image"
  style="...">

Rich text can contain inline images. The image is stored as an attachment.

If the attachment has been deleted, the HTML will contain data-asana-deleted="true", and some of the other attributes, such as the URLs, will not be present.

The image URLs expire after a few minutes.

External media embeds (iFrames)

Reading an external media embed

<object
  type="application/vnd.asana.external_media"
  data-asana-type="attachment"
  data-asana-gid="1234"
  data="{embeddable-url}"
>
  <a href="{linkable-url}">{linkable-url}</a>
</object>

You can embed Figma, Loom, YouTube, etc. within rich text. The effect is similar to an HTML iFrame. There is a fixed, predefined list of external media sources that are supported:

• Adobe XD
• Canva
• Figma
• InVision
• Loom
• LucidChart
• Miro
• Vimeo
• Whimsical
• Wistia

Milestones and goals

Reading milestones

<object
  type="application/vnd.asana.project_milestones"
  data-asana-gid="<gid-of-project>"
  data-asana-type="project">[...]</object>

Reading goals

<object
  type="application/vnd.asana.project_goals"
  data-asana-gid="<gid-of-project>"
  data-asana-type="project">[...]</object>

Rich text can contain:

• A list of all milestones in the specified project
• A list of all goals that are supported by the specified project

When reading, the inner HTML of the <object> tag will contain a list of the first five milestones/goals, followed by "..." if there are more than five in total. When writing, the inner HTML is ignored and can be empty.

Reading defensively

Custom handling external media <object>

const richText = '<body><object style="display:block" type="application/vnd.asana.external_media" data="https://www.youtube.com/embed/VqnMA3K6-e0"><a href="https://www.youtube.com/embed/VqnMA3K6-e0">https://www.youtube.com/embed/VqnMA3K6-e0</a></object></body>'
const parser = new DOMParser();
const richTextDocument = parser.parseFromString(richText, "text/html");

const objects = richTextDocument.querySelectorAll("object");

for (let i = 0; i < objects.length; i++) {
    replacement = null;

    switch(objects[i].type) {
        case "application/vnd.asana.external_media":
            replacement = richTextDocument.createElement('iframe');
            replacement.width = 420;
            replacement.height = 315;
            replacement.src = objects[i].data;
            break;
        default:
            replacement = richTextDocument.createElement('div');
            replacement.innerHtml = objects[i].innerHTML;
    }

    if (replacement) {
        objects[i].parentElement.replaceChild(replacement, objects[i]);
    }
}

richTextDocument.body.childNodes.forEach (child => {
    document.body.append(child);
});

We are actively adding new rich text formats to various objects in Asana. An existing app will break if not built defensively. Apps should use parsers and display logic that is forward compatible with unknown future rich text formats.

To do this, Asana provides two mechanisms to parse and display tags that the app doesn't explicitly support:

• Defaults that render in a WebView
• Guidelines for how to handle new tags

You can read more about rich text changes in this forum post.

Render rich text in a WebView

You can expect the rich text HTML to render reasonably in a WebView if you apply the following CSS style to the wrapping DOM node: overflow-wrap: break-word; white-space: pre-wrap;. This won't look exactly like it does in Asana, but it will ensure users read it in the same way.

How to handle new tags (no WebView)

An <object> with an unhandled type

Render the <object> tag as a block and render the contained HTML with the same behavior as if it were not inside an <object>. We will never send an <object> tag nested inside another <object> tag.

An <img>

Fall back to either the alt text or the src link if the image can’t be displayed. Wrap the text with newlines like \n<alt text>\n since <img> tags are blocks.

Empty elements except <img> and <hr>

Empty tags are described here. It is ok to omit them. Render as a new line if the tag is a block.

Other semantic non-terminal tags

Ignore the tag and render whatever is inside. Follow the HTML convention for whether it is a block or not.

Writing rich text

When writing rich text to the API, you must provide similarly structured, valid XML. The text must be wrapped in a <body> tag, all tags must be closed, balanced, and match the case of supported tags, and attributes must be quoted. Invalid XML, as well as unsupported tags, will be rejected with a 400 Bad Request error. Only <a> tags support attributes, and any attributes on other tags will be similarly rejected.

Links

For <a> tags specifically, to make it easier to create @-mentions through the API, we only require that you provide the GID of the object you wish to reference. If you have access to that object, the API will automatically generate the appropriate href and other attributes for you. For example, to create a link to a task with GID "123", you can send the tag <a data-asana-gid="123"/> which will then be expanded to <a href="https://app.asana.com/0/0/123/f" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="task" data-asana-gid="123">Task Name</a>. You can also generate a link to a task in a specific project or tag by including a data-asana-project or data-asana-tag attribute in the <a> tag. All other attributes, as well as the contents of the tag, are ignored.

To keep the contents of your tag and make a custom vanity link, include the property data-asana-dynamic="false" when setting the contents of the tag. You would send <a data-asana-gid="123" data-asana-dynamic="false">This is some custom text!</a> and receive <a data-asana-accessible="true" data-asana-dynamic="false" data-asana-type="task" data-asana-gid="123">This is some custom text!</a>

If you do not have access to the referenced object when you try to create a link, the API will not generate an href for you, but will instead look for an href you provide. This allows you to write back <a> tags unmodified even if you do not have access to the resource. If you do not have access to the referenced object and no href is provided, your request will be rejected with a 400 Bad Request error. Similarly, if you provide neither a GID nor a valid href, the request will be rejected with the same error.

Inline images

Writing an inline image (after uploading the attachment)

<img data-asana-gid="1234">

When writing an inline image, you don't need most of the attributes; all you need is the data-asana-gid. To write HTML that includes a new inline image:

1. Upload the image as an attachment with a call to POST /attachments.
2. Make a second API call to write the rich text, using the returned GID as the data-asana-gid field of the <img> tag.

External media embeds

Writing an external media embed

<object
  type="application/vnd.asana.external_media"
  data-asana-gid="1234"
></object>

To write rich text that contains a new external media embed:

1. Create URL attachment with a call to POST /attachments, with { ..., "resource_subtype": "external", "url": "<your_url>" }. Important: Use the URL that would appear in the browser address bar (e.g. https://youtube.com/watch?v=...), NOT the embeddable URL (e.g. https://youtube.com/embed/...).

2. Make a second API call to write the rich text, using the returned GID as the data-asana-gid field of the <object> tag. You don't need the inner HTML and you only need a couple of the <object> tag attributes: All that is needed is <object type="application/vnd.asana.external_media" data-asana-gid="..."></object>

Writing defensively

When processing rich text and sending it back

It is okay to ignore tags or attributes on tags that are unknown for rendering/processing. It is important to send everything back (attributes and inner content) to avoid data loss.

Note: <object> is an exception where it is acceptable to not send any inner content back (all inner content in <object> will be ignored).

If you plan to write an editor

If the tag and attributes are known, but it contains unknown attributes, it must be treated as unknown.

If a tag is unknown, first determine if the tag is block or inline, then render it as a block or inline atomic and non-copiable (and non-cut-and-paste-able) editor node (all inner content is non-editable). This is because we don’t know if the unknown node has constraints on inner content or where it can appear. The node must also keep track of all attributes and inner content to be serialized back.

SCIM

Asana supports SCIM 2.0 operations at https://app.asana.com/api/1.0/scim. Okta provides documentation for understanding SCIM.

Only Service Accounts in Enterprise Domains can access SCIM endpoints.

Service provider configuration endpoints

User endpoints

Examples

Request: GET https://app.asana.com/api/1.0/scim/Users?filter=userName eq "johnsmith@example.com"

Response: 200 OK

{
    "Resources": [
        {
            "id": "1",
            "name": {
                "familyName": "John",
                "givenName": "Smith",
                "formatted": "John Smith"
            },
            "userName": "johnsmith@example.com",
            "emails": [
                {
                    "value": "johnsmith@example.com",
                    "primary": true,
                    "type": "work"
                }
            ],
            "active": true,
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "title": "Software Engineer",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "department": "R&D"
            }
        }
    ],
    "totalResults": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ]
}

Request: POST https://app.asana.com/api/1.0/scim/Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "userName": "johnsmith@example.com",
    "name": {
        "formatted": "John Smith"
    },
    "emails": [
        {
            "primary": true,
            "value": "johnsmith@example.com"
        }
    ],
    "active": true,
    "title": "Software Engineer",
    "preferredLanguage": "en",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "R&D"
    }
}

Response: 201 Created

{
    "id": "1",
    "name": {
        "familyName": "John",
        "givenName": "Smith",
        "formatted": "John Smith"
    },
    "userName": "johnsmith@example.com",
    "emails": [
        {
            "value": "johnsmith@example.com",
            "primary": true,
            "type": "work"
        }
    ],
    "active": true,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "title": "Software Engineer",
    "preferredLanguage": "en",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "R&D"
    }
}

Request: PATCH https://app.asana.com/api/1.0/scim/Users/1

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "value": {
                "title": "Senior Software Engineer"
            }
        }
    ]
}

Response: 200 OK

{
    "id": "1",
    "name": {
        "familyName": "John",
        "givenName": "Smith",
        "formatted": "John Smith"
    },
    "userName": "johnsmith@example.com",
    "emails": [
        {
            "primary": true,
            "value": "johnsmith@example.com",
            "type": "work"
        }
    ],
    "active": true,
    "preferredLanguage": "en",
    "title": "Senior Software Engineer",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "R&D"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ]
}

Accepted attributes:

Group endpoints

Examples

Request: GET https://app.asanac.om/api/1.0/scim/Groups?filter=displayName eq "Marketing"

Response: 200 OK

{
    "Resources": [
        {
            "id": "1",
            "displayName": "Marketing",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "meta": {
                "resourceType": "Group"
            }
        }
    ],
    "totalResults": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ]
}

Request: POST https://app.asana.com/api/1.0/scim/Groups

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "Marketing",
    "members": [
        {"value": "1"},
        {"value": "2"}
    ]
}

Response: 201 Created

{
    "id": 1,
    "displayName": "Marketing",
    "members": [
        {"value": "1"},
        {"value": "2"}
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "meta": {
        "resourceType": "Group"
    }
}

Request: PATCH https://app.asana.com/api/1.0/scim/Groups/1

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "members",
            "value": [
                {
                    "value": "3"
                }
            ]
        }
    ]
}

Response: 204 No Content

SCIM Groups are equivalent to Asana teams.

Accepted attributes:

Deprecations

What is a breaking change?

In general, a breaking change refers to a change in an API that may require you to update your application or integration in order to avoid disruption. These changes may include:

Expanding the space of types or values that clients must handle, e.g.,

• Adding a new value to a built-in enum field
• Allowing a reference to be null, where it could not before

Changing the structure or meaning behind existing information, e.g.,

• Migrating a property to have a new type (such as boolean to enum)

Adding new restrictions to perform an existing operation in the system, e.g.,

• Only allowing a method to be called if some new condition is met, where this was not true before

Removing the types or values that clients can provide, e.g.,

• No longer allowing a value to be null where it could before
• Newly enforcing that a numeric value is nonzero
• Removing a property

Removing a capability of the system, e.g.,

• Removing a mutation or some of its behavior

Communicating about breaking changes

Whenever possible, the Asana API aims to preserve backwards compatibility for its users. Apps you write on top of the API now should, in ideal situations, continue to work indefinitely. However, there are a few rare cases where breaking changes are required. For example:

• When we identify a stability threat, we may need to partially limit or entirely deprecate the culprit feature in the API.
• When making a change in a backwards compatible way results in a cluttered, brittle, and confusing interface to Asana.
• When not making a breaking change poses a security vulnerability, such as when we migrated from SSLv3 to TLS 1.0.

If a breaking change is required, the API team will provide a number of resources to help our developers get through the change:

• We will communicate early, and through a variety of channels. We recommend that you join the developer community forum to learn about changes to the API.
• We will provide a clear description of the change, how it affects your requests, and a migration plan to follow to transition through the deprecation.
• We will designate a deprecation period during which you will be able to choose between both old and new behavior from the API, allowing you to test out the change without having to put your entire app at risk.

Response header notifications

While the previously-mentioned communication channels are the best place to learn about upcoming changes, the API itself will also alert you of upcoming changes. Shortly after we post communication, the API will begin sending Asana-Change headers in the responses. These headers will have two or three pieces of information:

• The unique name of the change
• A URL to our blog post describing the change
• Optionally, a flag indicating that your specific request would be affected.

This header may be present multiple times in the response if there are multiple ongoing changes. Here's an example of one of these headers:

Asana-Change: name=security_headers;info=https://asa.na/api-sh;affected=true
Asana-Change: name=other_change;info=https://asa.na/api-oc

Note: If your request is not affected, we will not claim affected=false. This is in case, during the deprecation, we detect that the change has a larger scope than initially thought. A request going from "you may be affected" to "you definitely are affected" is an acceptable update, but a request going from "you definitely are not affected" to "you definitely are affected" is not an acceptable update.

Request header options

During the deprecation period, you can test out how the API will behave by sending additional headers in your requests. Sending an Asana-Enable header including comma-separated names of features will turn those features on for that request. Sending an Asana-Disable header will do the opposite and turn those features off for that request.

If no header is specified, the default behavior will be determined by how far into the deprecation period we are:

• Before the start of the deprecation period (the "start date") the feature will be disabled, and it will not be possible to enable it.
• After the start date, the feature will be disabled by default, but you can begin choosing whether to enable or disable it.
• In roughly the middle of the deprecation period (the "activation date") the default behavior will switch and the feature will be enabled by default. You can continue to disable it with the appropriate header.
• At the end of the deprecation period (the "end date") the feature will be enabled and you will no longer be able to manually disable it.

The start, activation, and end dates will clearly be documented in our communications. These days may be pushed into the future if we discover that developers need more time to migrate their apps, but they are guaranteed to never occur sooner than documented.

These dates are arranged such that, if a developer happens to miss our communication and their app breaks when the default behavior changes on the activation date, they can begin sending the Asana-Disable header to restore the old behavior and use the remaining half of the deprecation period to make their app compatible.

Here is an example of how these headers would look:

Asana-Enable: security_headers,another_change
Asana-Disable: a_third_change

Aside from reserving the right to push the date of changes to a future date, the precise time during the activation date is not specified. However, since the default will only affect your integration if you do not pass either the Asana-Enable or Asana-Disable headers for a particular deprecation, you can ensure predictable behavior of our API for your app during the entire period, including throughout the activation date.

The way we recommend you implement these changes in your integration is this:

• Whenever you detect a new Asana-Change header, log these requests and be sure to take note that a change is coming. Recall that the info key in the header will contain a link with the details.
• Identify the nature of the upcoming deprecation and decide if your integration is sensitive to the change, paying particular attention to the cases where we return affected=true.
• If changes are necessary in your integration, test the new behavior manually by making requests with Asana-Enable set to the name of the deprecation. This should provide a clear example of the new behavior as it is implemented in our API.
• Implement the changes in your integration in such a way that it can handle the new behavior and be sure to pass the Asana-Enable header when you make requests. This will ensure that you will always get the new behavior regardless of when the default behavior changes.

At this point, your integration has been migrated to the new behavior. At any point after the end date the Asana-Enable header will be ignored by the Asana API and you can feel free to remove it. We strongly recommend keeping it all the way through the end date in case of unforseen circumstances that cause us to temporarily reset the default behavior from the new implementation to the deprecated behavior.

Client library support

The latest version of our official client libraries for Python, Java, PHP, and JavaScript all support sending custom headers and are able to use our deprecations framework. Consult the individual libraries for how to send headers with each request.

Authentication

Asana supports a few methods of authenticating with the API. Simple cases are usually handled with a personal access token, while multi-user apps utilize OAuth.

"Authorization: Bearer ACCESS_TOKEN"

• OAuth 2.0: We require that applications designed to access the Asana API on behalf of multiple users implement OAuth 2.0.
• Personal access tokens are designed for accessing the API from the command line or from personal applications.

OAuth

Most of the time, OAuth is the preferred method of authentication for developers, users, and Asana as a platform. If you are new to OAuth, take a moment to learn about it with this guide.

In addition to learning about how to use OAuth on the Asana platform, feel free to review the official OAuth spec.

At its core, OAuth is a mechanism for applications to access the Asana API on behalf of a user without the application having access to the username and password. Instead, apps get a token which they can use along with their own application credentials to make API requests.

What is OAuth?

While we recommend using a library to handle the details of OAuth, the following section describes the OAuth process. If you are already using a library or have a deep understanding of OAuth (and have registered an OAuth application), you may want to skip ahead to the quick reference.

1. If you have not already, you will need to register an application. Take note of the client ID, an application's username, and the client secret (which should be protected as a password).

2. A user will arrive at your application and click a button that says "Connect with Asana."

3. This takes the customer to the user authorization endpoint, which displays a page that asks the user if they would like to grant access to your third-party application.

4. If the customer clicks "Allow", they are redirected back to the application, bringing along a special code as a query parameter. (We are assuming the authorization code grant flow, which is the most common.)

5. The application can now use the token exchange endpoint to exchange the code, together with the client secret, for a bearer token (which lasts an hour) and a refresh token (which can be used to fetch new bearer token when the current one expires).

6. The application can make requests of the API using this bearer token for the next hour.

7. Once the bearer token expires, the application can again use the token exchange endpoint to exchange the refresh token for a new bearer token. This can be repeated for as long as the user has authorized the application.

Register an application

You must first register your application with Asana to receive a client ID and client secret. To do so, first visit the developer console and select Create new app.

You should supply your new application with:

• App name - A name for your application. A user will see this name when your application requests permission to access their account as well as when they review the list of apps they have authorized.
• Authentication URL - This is where users will be sent when they authenticate your app.
• Redirect URL - As described in the OAuth specification, this is where the user will be redirected upon successful or failed authentications. Native or command line applications should use the special redirect URL urn:ietf:wg:oauth:2.0:oob. For security reasons, non-native applications must supply a "https" URL (more on this below).

Optionally, you can upload an icon, a description, and other basic information about your application. Note that all of these attributes can be changed later, as well.

Once you have created an app, the OAuth tab in the sidebar will include a client ID, needed to uniquely identify your app to the Asana API, as well as a client secret.

Note: your client secret is a secret, and it should never be shared with anyone or checked into source code that others could gain access to.

Quick reference

• Applications can be created from the developer console.
• The endpoint for user authorization is https://app.asana.com/-/oauth_authorize
• The endpoint for token exchange is https://app.asana.com/-/oauth_token
• The endpoint for revoking a token is https://app.asana.com/-/oauth_revoke
• Asana supports the authorization code grant flow.
• Once an access token has been obtained, your application can make requests on behalf of the user.

User authorization grant

Request

Send a user to oauth_authorize

<a href="https://app.asana.com/-/oauth_authorize
?client_id=753482910
&redirect_uri=https://my.app.com
&response_type=code
&state=thisIsARandomString
&code_challenge_method=S256
&code_challenge=671608a33392cee13585063953a86d396dffd15222d83ef958f43a2804ac7fb2
&scope=default">Authenticate with Asana</a>

Your app redirects the user to https://app.asana.com/-/oauth_authorize, passing parameters along as a standard query string:

Response

If either the client_id or redirect_uri do not match, the user will simply see a plain-text error. Otherwise, all errors will be sent back to the redirect_uri specified.

The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either case, the user will be redirected back to the redirect_uri.

User is redirected to the redirect_uri

https://my.app.com?code=325797325&state=thisIsARandomString

Preventing CSRF attacks

The state parameter is necessary to prevent CSRF attacks. As such, you must check that the state is the same in this response as it was in the request. If the state parameter is not used, or not tied to the user's session, then attackers can initiate an OAuth flow themselves before tricking a user's browser into completing it. That is, users can unknowingly bind their accounts to an attacker account.

Requirements

The state parameter must contain an unguessable value tied to the user's session, which can be the hash of something tied to their session when the OAuth flow is first initiated (e.g., their session cookie). This value is then passed back and forth between the client application and the OAuth service as a form of CSRF token for the client application.

Additional resources

• OAuth 2.0 Security Best Current Practice
• Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters

OAuth scopes

The Asana API supports a small set of OAuth scopes you can request using the scope parameter during the user authorization step of your authentication flow. Multiple scopes can be requested at once as a space-delimited list of scopes. An exhaustive list of the supported scopes is provided here:

Token exchange endpoint

Request

When your app receives a code from the authorization endpoint, it can now be exchanged for a proper token.

If you have a client_secret, this request should be sent from your secure server. The browser should never see your client_secret.

App sends request to oauth_token

{
  "grant_type": "authorization_code",
  "client_id": "753482910",
  "client_secret": "6572195638271537892521",
  "redirect_uri": "https://my.app.com",
  "code": "325797325",
  "code_verifier": "fdsuiafhjbkewbfnmdxzvbuicxlhkvnemwavx"
}

Your app should make a POST request to https://app.asana.com/-/oauth_token, passing the parameters as part of a standard form-encoded post body.

The token exchange endpoint is used to exchange a code or refresh token for an access token.

Response

In the response, you will receive a JSON payload with the following parameters:

{
  "access_token": "f6ds7fdsa69ags7ag9sd5a",
  "expires_in": 3600,
  "token_type": "bearer",
  "refresh_token": "hjkl325hjkl4325hj4kl32fjds",
  "data": {
    "id": "4673218951",
    "name": "Greg Sanchez",
    "email": "gsanchez@example.com"
  }
}

Authorization code grant

To implement the authorization code grant flow (the most typical flow for most applications), there are three steps:

1. Send the user to the authorization endpoint so that they can approve access of your app to their Asana account

2. Receive a redirect back from the authorization endpoint with a code embedded in the parameters

3. Exchange the code via the token exchange endpoint for a **refresh_token** and, for convenience, an initial access_token.

4. When the short-lived access_token expires, the **refresh_token** can be used with the token exchange endpoint, without user intervention, to get a fresh access_token.

The token that you have at the end can be used to make requests to the Asana API on the user's behalf.

Proof key for code exchange (PKCE) OAuth extension

User authorization endpoint

{
  ...
  "code_challenge": "671608a33392cee13585063953a86d396dffd15222d83ef958f43a2804ac7fb2",
  "code_challenge_method": "S256"
}

Token exchange endpoint

{
  ...
  "code_verifier": "fdsuiafhjbkewbfnmdxzvbuicxlhkvnemwavx"
}

PKCE proves the app that started the authorization flow is the same app that finishes the flow. You can read more about it here. In short, the process is as follows:

1. Whenever a user wants to OAuth with Asana, your app server should generate a random string called the code_verifier. This string should be saved to the user (as every code_verifier should be unique per user). This should stay on the app server and only be sent to the token exchange endpoint.

2. Your app server will hash the code_verifier with SHA256 to get a string called the code_challenge. Your server will give the browser only the code_challenge & code_challenge_method. The code_challenge_method should be the string "S256" to tell Asana we hashed with SHA256. More specifically, code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).

3. The browser includes code_challenge & code_challenge_method when redirecting to the user authorization endpoint.

4. The app server should include the code_verifier in its request to the token exchange endpoint.

Asana confirms that hashing the code_verifier with the code_challenge_method results in the code_challenge. This proves to Asana the app that hit the user authorization endpoint is the same app that hit the token exchange endpoint.

Secure redirect endpoint

As the redirect from the authorization endpoint in either grant procedure contains a code that is secret between Asana's authorization servers and your application, this response should not occur in plaintext over an unencrypted http connection. Because of this, we enforce the use of https redirect endpoints for application registrations.

For non-production or personal use, you may wish to check out stunnel, which can act as a proxy to receive an encrypted connection, decrypt it, and forward it on to your application. For development work, you may wish to create a self-signed SSL/TLS certificate for use with your web server; for production work we recommend purchasing a certificate from a certificate authority. You may review a short summary of the steps for each of these processes here.

Your application will need to be configured to accept SSL/TLS connections for your redirect endpoint when users become authenticated, but for many apps, this will simply require a configuration update of your application server. Instructions for Apache and Nginx can be found on their respective websites, and most popular application servers will contain documentation on how to proceed.

Token deauthorization endpoint

Request

An authorization token can be deauthorized or invalidated by making a request to Asana's API.

Your app should make a POST request to https://app.asana.com/-/oauth_revoke, passing the parameters as part of a standard form-encoded post body.

The body should include a valid refresh token, which will cause the refresh token and any associated bearer tokens to be deauthorized. Bearer tokens are not accepted in the request body since a new bearer token can always be obtained by reusing an authorized refresh token.

Response

A successful response with a 200 status code indicates that the token was deauthorized or not found. An unsuccessful response with a 400 status code will be returned if the request was malformed due to missing any required fields or specifying an invalid token (such as a bearer access token).

Personal access token

Personal access tokens (PATs) are a useful mechanism for accessing the API in scenarios where OAuth would be considered overkill, such as access from the command line and personal scripts or applications. A user can create many, but not unlimited, personal access tokens. When creating a token, you must give it a description to help you remember what you created the token for.

Personal access tokens should be used similarly to OAuth access tokens when accessing the API (i.e., passing them in the Authorization header)

Example cURL request authenticating with a PAT

curl https://app.asana.com/api/1.0/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

You can generate a personal access token from the Asana developer console. See the authenticating section for detailed instructions on getting started with PATs.

For security, you should regularly review the list of personal access tokens you have created and deauthorize those that you no longer need.

Remember to keep your tokens secret and treat them just like passwords. Your tokens act on your behalf when interacting with the API. As such, do not hardcode them into your programs. Instead, opt to use them as environment variables.

OpenID Connect

Asana also supports the OpenID Connect protocol for authenticating Asana users with your applications. That is, in addition to the normal code and token response types for the OAuth flow, you can also use the id_token response type.

For this response type, you are not granted an access token for the API, but rather given a signed JSON Web Token containing the user's ID along with some metadata. If you want to allow users to log into your services using their Asana account, the OpenID Connect protocol is an ideal way to authenticate an Asana user. To obtain an ID token, you must request the openid scope during the authentication flow.

It is also possible to obtain an ID token alongside an authorization code in the authorization code grant flow by using the (space-delimited) code id_token response type. If you do, the redirect parameters will include the ID token in addition to everything you would normally receive.

To access additional information about the user in a standardized format, we also expose a user info endpoint that can provide the user's name, email address, and profile photo. This data is available by making a GET request to https://app.asana.com/api/1.0/openid_connect/userinfo with an OAuth access token that has the openid scope. Depending on the scopes tied to that token, you will receive different pieces of data. Refer to our list of OAuth scopes to determine which additional scopes you need to get the data you want.

Metadata about our OpenID Connect implementation is also made available through OpenID Connect's discovery protocol. Making an unauthenticated GET request to https://app.asana.com/api/1.0/.well-known/openid-configuration will provide all the details of our implementation necessary for you to use OpenID Connect with Asana's API.

Custom external data

Custom external data allows a client application to add app-specific metadata to tasks in the API. The custom data includes a string gid that can be used to retrieve objects and a data blob that can store character strings.

The blob may store unicode-safe serialized data such as JSON or YAML. The external gid is capped at 1,024 characters, while data blobs are capped at 32,768 characters. Each object supporting external data can have one gid and one data blob stored with it. You can also use either or both of those fields.

The external gid field is a good choice to create a reference between a resource in Asana and another database, such as cross-referencing an Asana task with a customer record in a CRM, or a bug in a dedicated bug tracker. Since it is just a unicode string, this field can store numeric IDs as well as URIs. However, when using URIs, extra care must be taken that the parameter is escaped correctly when forming queries . By assigning an external gid, you can use the notation external:custom_id to reference your object anywhere that you may use the original object gid.

Note: You will need to authenticate with OAuth, as the gid and data are app-specific, and these fields are not visible in the UI. This also means that external data set by one Oauth app will be invisible to all other Oauth apps. However, the data is visible to all users of the same app that can view the resource to which the data is attached, so this should not be used for private user data.

Overview of webhooks

Webhooks allow an application to be notified of changes in Asana.

This is similar to our events resource, but webhooks "push" events via HTTP POST rather than expecting integrations to repeatedly "poll" for them. For services that are already accessible on the internet, this is often more convenient and efficient.

However, webhooks require a server to be accessible over the internet at all times to receive the event. For most simple integrations, events provide much of the same benefits while using a significantly simpler implementation which does not require maintaining an internet-accessible server.

Webhooks and events streams are served from the same infrastructure, where, on average, events are delivered within a minute of occurring. This system is designed for at most once delivery, meaning in exceptional circumstances we may fail to deliver events. Furthermore, webhooks cannot be replayed once delivered. For these reasons, if your use case requires strong guarantees about processing all changes on a resource and cannot tolerate any missing events, regardless of how rare that might be, we recommend building a fallback polling system that fetches the resource periodically as well. Note that, if your server does not respond to a webhook with a successful HTTP status code within 10 seconds, Asana will try to resend the webhook for up to 24 hours before giving up.

Setting up a webhook

In order to start receiving webhook events about an Asana resource, you will need to establish a webhook connnection and complete the initial handshake. This requires that you create and host an internet-accessible webhook server.

The following video tutorial walks you through the process of:

1. Setting up an example webhook server [1:58]
2. Setting up business logic for the webhook handshake [3:45]
3. Establishing a webhook on an Asana resource [6:45]
4. Verifying and receiving webhook events[9:02]

You can find the tutorial source code here.

The webhook handshake

In order to ensure that the receiving server is available to receive incoming events from a webhook Asana will POST to the requested target endpoint during the webhook creation request. In other words, the outgoing webhook creation request will wait to return until another full POST request from Asana's servers to the target has been completed, then the webhook creation request can return with a successful response.

Note: This means that your server must be able to handle being blocked on the outgoing create request while still being able to receive and handle an incoming request. A common reason that webhook handshakes fail is that servers are not able to asynchronously handle the handshake request.

Included in the webhook handshake is a HTTP header called X-Hook-Secret. To successfully complete the handshake, the receiving server should echo back the same header with the same value and a 200 OK or 204 No Content response code.

The purpose of this header is to provide a shared secret that both Asana and the receiving server both store. This is the only time it will be transmitted. In future webhook events, Asana will use this key to compute a signature over the webhook callback request's body which can be used to verify that the incoming request was genuine (details below). We strongly recommend that you take advantage of this security feature and reject webhooks that have an invalid signature.

For an example of how this might be implemented in code, see our sample implementation in Node.js and Python

Filtering

Webhook events will "propagate up" from contained objects through to parent objects. For example, changes to comments will be sent to webhooks on the parent task and to ones on the task's projects. This way, a webhook on a project will be notified of all changes that occur in all of its tasks, subtasks of those tasks, and comments on those tasks and subtasks.

This can be a lot of data, some of which might not be relevant to a particular integration, so Asana's webhooks have a filtering feature which allows integrations to specify only the types of changes that they care about. By specifying the list of WebhookFilters on webhook creation an integration can select just the subset of events it wants to receive. When filters are specified on the webhook, events will only be delivered if they pass any of the filters specified when creating the webhook.

To reduce the volume of data to transfer, webhooks created on teams, portfolios, and workspaces must specify filters. In addition, the set of event filters that can be placed on a team-level or workspace-level webhook is more limited than filters for webhooks that are created on lower-level resources:

• Webhook events from tasks, subtasks, and stories won't be propagated to these higher-level webhooks, so all changes on these resources are automatically filtered out.
• Webhook events from project resources can be filtered for these actions: added, removed, deleted, undeleted, and changed.
• Webhook events from team_membership resources can be filtered to actions added and removed.
• Webhook events from workspace_membership resources can be filtered to added and removed.

Actions

Actions define the type of action that was taken on the resource to trigger an event for your webhook. When you receive a webhook event, there will be an associated action in the event response that indicates the action that triggered the event. Additionally, actions are used in webhook filters. You can specify an action and a resource_type in the filters parameter when establishing a webhook so that you will only receive events matching the action specified for the resource in your filter.

The following is a list of actions that we support:

• added - a new resource was created
• changed - the resource was modified
• deleted - the resource itself was deleted
• removed - the resource was removed from a parent
• undeleted - the deletion of the resource was undone

Resources and actions

Below is a list of resources and actions that can trigger an event for those resources. This is not an exhaustive list, but should cover the most common use cases.

• Attachment - deleted, undeleted
• Portfolio - added, deleted, removed
• Project - added, changed, deleted, removed, undeleted
• Project Membership - added, removed
• Project Template Configuration - added, deleted, removed
• Project Template Configuration Membership - added, removed
• Section - added, changed, deleted, undeleted
• Story: type: <all other types> added, removed, undeleted
• Story: type: comment added, changed, removed, undeleted
• Tag - added, changed, deleted, undeleted
• Task - added, changed, deleted, removed, undeleted
• Team - added, changed, deleted
• Team Membership - added, removed
• Workspace - added, removed, changed
• Workspace Memberships - added, removed

For example, let's say you establish a webhook for an attachement by providing the GID of an attacment in your resource parameter. This means that based on the resource and action definition for attachment above, a deleted or an undeleted action will trigger your attachement webhook.

Example webhook servers

The following are example webhook servers that demonstrates the features of Asana webhooks. This includes how to handle the webhook handshake as well as how to receive and verify webhook events.

To try out this demo out for yourself, be sure to generate a new personal access token, then follow the instructions in README.

• Node.js example server
• Python example server