A note about deprecating integer IDs

Fixing breaks: the fast way, and the correct way

As with any software product we continuously iterate on our API. Whenever possible we do this in a way that doesn’t create a breaking change in our API interface, but sometimes we have to make a modification that we know will affect our apps. We built our deprecations framework to make it as easy as we can to empower our developers to fix breaks quickly when changes happen.

We are currently in the middle of one such change as we replace integer IDs with string IDs. We are deprecating the number-based id field in favor of a string-based gid field. The fastest way to fix your application is to send a HTTP header on all requests: Asana-Disable: string_ids which will disable the behavior that only provides strings. Note that this temporary solution will only be valid until 2020-02-11. The full fix is to replace all usage of id in favor of gid for all interactions with our API (including webhooks, which can be configured for this in our developer console ).

We are migrating from integer IDs to string IDs due to fundamental issues in representing large integers in Javascript. For more information about this please reference our earlier post about string IDs. We have been using our deprecations framework to communicate this change but we understand that some applications may not have been prepared for such a sweeping modification of our API interface. To that end, we hope that the small change of adding this header to all requests while you convert your application to the new interface will be a fast and easy way to get up and running again!

We encourage you to take this opportunity to not only make the modifications for your integration to restore its functionality but also to familiarize yourself with the features of our deprecation framework, because this is how Asana is going to evolve our API over time. When we have an upcoming deprecation in the works we will send an Asana-Change header which is intended to be used by your integration to alert a maintainer however you wish (logging, email, warning page) whenever there is an API interface change for you to handle. Please consider building in alerts that take advantage of this header to keep you up to date with what we’re creating in Asana’s API as we continue to iterate on it!

In addition, we’ll keep our page on deprecations up to date with all our API changes and timelines for them.

Thank you for your understanding and support! If you have any questions, concerns, or need assistance please head over to the Asana Forum’s Developers and API category to spark a discussion!

Latest Asana API Updates

There have been a number of exciting and long-asked-for updates in Asana’s API since our last newsletter. Here are some features that we’ve recently shipped—and upcoming changes to keep an eye on.

Advanced Search

Developers have long been asking for more powerful server-side querying to find data in Asana. While some basic filtering has been available for a long time, we often hear that client-side filtering is still necessary for more advanced use cases. This can slow apps down and make their implementation more complicated. It also means apps are receiving more data than they actually care about.

To solve these issues we’ve released our search API. This feature exposes much of the functionality in Asana’s Advanced Search to integrations, meaning that developers can now combine a variety of filters to select exactly the data their apps need. Now apps can request only tasks with a particular custom field or a combination of assignee and due date (as two common examples) and get the data back fast enough to feel interactive to users.

This feature represents a major improvement in how precisely apps are able to request data. Be sure to read the docs to see if it fits your use case!

Reacting to changes in our API

At Asana we try hard to maintain our published interface that your integrations rely on, but sometimes this is not possible. In particular, as new features are added to our web product and our API, the interface can be affected in a non-backwards-compatible way.

As Asana is rapidly creating and evolving features, we want to make this reality as painless as possible while not blocking improvements to the product. This is why we built our releases and deprecations framework: to enable apps to programmatically detect and surface upcoming changes with plenty of time to react and without requiring a developer to keep a constant eye on this blog. Once a developer is aware of the change, our framework enables them to switch to the new behavior on their own timeline. Developers can set special headers on individual requests to choose between old and new behavior and understand how the change affects them.

It’s very important for all developers to understand how to migrate through breaking changes so please read the full documentation about our deprecation process.

New Rich Text

Users in Asana can format text to style it with bolding or italics, or give it structure with lists or hyperlinks, but our existing support for this was difficult to use in the API. Worse, it was nearly impossible to parse links in Asana in a straightforward way (external hyperlinks as well as @-mentions to users / projects / tasks) and to understand to whom or where the link is referencing. To rectify this we are replacing rich text to provide better support for these features. Now it’s possible for integrations to parse and update a strict XML representation of rich text to use these features, including special attributes which provide information that had previously been complicated to find. For apps already using our rich text, this change will be managed by our deprecation framework and is available now for making the transition.

Asana is moving to string IDs

A upcoming breaking change that all apps must handle is the switch from integers to strings for object IDs in Asana. In order to help you transition, our API now returns a string gid field everywhere that the integer id field is returned. Integrations should use gid to reference Asana objects moving forward. For more information, refer to our original post on string IDs and how to use our deprecation framework and for all the latest updates visit the announcement topic in the Asana Forum

Project Status Updates

When users post status updates for their projects it builds a history of how that project is progressing. Accessing this data can be useful for integrations that want to generate reports about these projects. Integrations can also give their users the ability to create a status update in the report without ever leaving the integration. To support these use cases you can now read the full history of status updates and create new ones through our API. Find more information in our API reference for project statuses.

Client libraries are now up to date with these features

With all the new features that we’ve released recently, we’ve also taken the time to support them in our official client libraries. Now is a good time to upgrade and start using the latest features of Asana’s API.

Integer to String ID conversion

Asana currently uses numerical IDs for all references, but we are running out of them. Once we surpass 253, JavaScript loses precision and is no longer able to accurately represent every ID. You can observe this by opening up a JavaScript console and seeing that 2**53 + 1 == 2**53 evaluates to true. Because of this, we must move away from numerical IDs before we reach that point, and by consequence that means our developers also need to move away from numerical IDs.

The API team is actively working on this migration both within our internal code and in the public API’s interface. Because of the scope and complexity of this change internally, you will start to see some of these changes leak (in backwards compatible ways) before we’re ready for you to move to string IDs yourself. However, we want to share the plan with you to provide clarity and minimize confusion during this change.

The preparation

Starting now, you will start to see objects containing two ID fields: the current, numerical id field and a new, string gid field. Additionally, places where the API accepts IDs as inputs will begin to accept both numbers and strings depending on which key you send to us. Here’s an example of the new schema for objects in our API. Notice how the id field is an integer in the JSON payload and gid is a string in double quotes:

"data" : {
  "id" : 153678405088703,
  "gid" : "153678405088703",
  "name" : "An Asana task"

If you store Asana IDs in a service outside Asana (such as an SQL table), please start planning how you will migrate IDs in these services to become strings. For example, if you are using an SQL table, you will want to change from a type like BIGINT to a type like VARCHAR.

The change

Once we have comprehensively confirmed that the API is fully able to support string IDs, we will be using our deprecations framework for the migration. You’ll be able to send a flag in your request headers that enables the new behavior. This consists of two aspects:

  1. When enabled, objects will not contain an id field. They will contain only the gid field as their ID.
  2. When enabled, the API will reject API requests that use numbers instead of strings to reference objects.

After we have opened this up with the deprecations framework, the old behavior will be the default for about six months. Then, the new behavior will become the default and there will be another six months during which you can select the old behavior. After that, the API will operate with the new behavior fully and the old behavior will not be available. (Please refer to our deprecations documentation for more information about this process.)

The future

After the migration is complete, IDs will only ever be strings. Additionally, that is the only guarantee that Asana can make about IDs. We make no guarantee that IDs will simply be the string representation of integers—newly issued IDs may have letters in them as well. Therefore, you must transition your format to handle strings.

Please let us know if you have any questions about string IDs, and we’ll answer them in this thread. We will be sending out more communication over the coming months as we get closer to completion of the work on our end and the finalization of a timeline.


What does gid mean?

This stands for “global ID.” In Asana, IDs are globally unique, across all workspaces and even across all data types. gid feels like a logical alternative to id and also conveys more information about Asana’s schema.

My code was already using strings. Why not just make id a string instead of removing it?

While we will do our best to make sure that all developers hear about this change in some form, the truth is that some will still fall through the cracks. There are also several libraries and frameworks out there that will silently coerce strings to numbers where asked, and if we left in the id field these applications might never notice the change.

If we remove this field, we force every developer to react during this migration period, during which they still have a chance to choose between old and new behavior and can quickly recover if their app breaks. If we don’t remove this field, it’s possible for a developer not to notice the change during the migration period. Then, after the migration period is over and the new behavior is cemented, we could send an ID with letters in it that would break their app and there would be no safe recovery.

What about existing IDs?

Any ID that was already issued by Asana will continue to be the only ID associated with that object and will not change with this migration. If you have an ID, the only transformation you need to apply is turning it into a string for storage (and using this string for the gid field moving forward).

How long will these new IDs be?

Asana’s new string IDs will not exceed 31 characters in length. If you are using an SQL table, this means that you can use VARCHAR(31) as the column type for IDs. This will allow the storage of IDs in at most 32 bytes (with an extra byte allocated by your database to encode the length of each ID).

New Rich Text

As the Asana web product has developed over the years and acquired new formatting, the API hasn’t kept up with all of the new additions owing to the fact that we needed to maintain backwards compatibility. Over time, lack of access to these additions have started to hinder app functionality. In one example, our format for representing links to other Asana objects (such as when you @-mention another user or task) didn’t communicate enough of the useful information about these links. The Asana API is now happy to announce that we’re addressing these issues in our “new rich text” update.

The full documentation for this new feature has been published, but to summarize, there are two major changes to be aware of when using this new format:

  • All text must be valid, supported XML.
    • This means that all rich text going in and out of the API will be wrapped in a root <body> tag.
    • This also means that unsupported XML tags will be rejected.
  • Link tags will contain attributes about the object they link to.
    • For example, they will have an data-asana-type object that tells you whether the link points to a task, a user, a project, or another type.
    • This feature can also be used to have Asana automatically generate links for you. By adding a data-asana-gid attribute with the ID of the object you wish to link to, the API will generate the correct href target.

See the long-form documentation for a list of supported tags and how to read and write to rich text fields.

The Asana API recently launched a deprecation framework that allows developers to safely migrate to new features or through breaking changes. This framework is now being used to roll out the new rich text. Please refer to the deprecations documentation for more information on how to get this new behavior.

Beginning today, you can send Asana-Enable: new_rich_text in the headers of your API requests to enable the new format and begin using this new feature.

Beginning on October 15th 2018, the default behavior will change and requests that don’t explicitly choose either the old or new format will start to receive the new format. If this triggers an issue with your app, you can send the Asana-Disable: new_rich_text header to continue using the old format.

On December 17th 2018, the new behavior will become permanent. All responses will use the new format and enforce the new validation, and you will no longer be able to use the old behavior.

Breaking Changes in the API

Deprecation Process

There are unfortunately some circumstances where we cannot roll out changes in a backwards compatible way. To help users of the Asana API get over these hurdles, we have created a formalized deprecation process that we’ll be using to release these breaking changes.

In short, we will provide deprecation periods during which you’ll be able to select between old and new behavior on a per-request level, allowing you to observe the differences and test them in a controlled manner. This is done by sending Asana-Enable and Asana-Disable headers in your requests with the names of the features you want to turn on or off. We strongly encourage you to read the full documentation for this process.

Security Headers

Right now, the responses from the API will include two security-related headers: Content-Security-Policy-Report-Only and Strict-Transport-Security. We would like to send additional security headers in our responses, but these additional headers may cause problems with some improperly configured browser clients. Because of this, we will be using the deprecations process mentioned above to roll out the following additional headers:

Starting now, you can send Asana-Enable: security_headers in the headers of your API requests to enable the new behavior and begin receiving these additional headers.

Beginning on September 28th 2018, the default behavior will change and requests that don’t explicitly choose to enable or disable these headers will start to receive the new security headers in the responses. If this triggers an issue with your app, you can send the Asana-Disable: security_headers header to disable them.

On November 15th 2018, the new behavior will become permanent. All responses will contain the new security headers, and you will no longer be able to disable them.

Keep an eye on our blog and community forum for the latest information about upcoming API changes.

Subtasks, Stories, and Start Dates - July 2018 API Updates

Subtask Ordering

Some of you have long been asking for the ability to insert subtasks in a particular order, or to reorder subtasks within a parent task. Well, the API team has finally cleared out a five-year-old TODO in our codebase and has implemented this feature! Just like when adding tasks to or reordering tasks in a project, you can now specify insert_before or insert_after when calling the setParent endpoint. The new parameters are detailed in our documentation for subtasks.

Editing and Pinning Stories

Since March, the web app has been letting users edit their comments in tasks, and now you can edit them in the API. Comment stories also now have an is_edited field to reflect whether they’ve been edited since creation. We’ve also exposed an is_pinned field for comment and attachment stories that can be set through the API to pin a story to the top of the task. Read more about these fields in our documentation for stories.

Project Start Dates

Another recent addition to the web app is start dates for projects, which have also made it to the API. You can read and write to the start_on field on projects for this new data. Note: project start dates are a premium-only feature.

Cost Limiter

We’ve added a new kind of rate limiting to the API based on the “cost” of your requests. Developers have always been able to choose exactly the data they need using our opt_fields parameter, but the amount of data selected directly affects the amount of resources required to construct the response. We’re now allotting a per-minute quota based on these costs, and a series of extremely expensive requests will result in 429 Too Many Requests responses. Very few developers (about 0.0002%) should actually encounter this, but if you happen to be one of the few, these responses will contain the usual Retry-After header that indicates how long you should wait before trying again. You can read more about this new limiter in our rate limiting documentation.

We’ve got more to show you in the coming months, so be sure to subscribe to our developer newsletter using the form in the sidebar.

Dependent on API - April 2018 API Updates

Dependencies make Timeline available to integrations

In late March, Asana launched our newest feature: Timeline, a tool to enable project planners and contributors organize the sequencing and timing of their work. To support integrations that would like to use Timeline, we shipped a long-standing Asana feature to our API users: dependencies.

While dependencies existed in Asana before Timeline, they became more useful with this new way to view project progress. Timeline uses dependencies to draw the lines between tasks, so setting and adjusting dependencies and start/end dates enables integrations to set up workflows that are useable in the Timeline view. This means that integrations can now take advantage of new use cases with Timeline to connect to other apps or to build custom workflows with Asana’s API.

Batch API calls for faster processing

Making API calls sequentially one after another can lead to slow-feeling integrations. Attempting to improve performance through making parallel requests is complex and requires careful engineering. To provide a middle ground, Asana has launched a batch API to make bulk operations easy. This has several benefits, including making parallelization feasible for browser integrations (which are currently limited by the browser to a small number of parallel requests). It also reduces the round-trip latency costs to only occur once per batch instead of once per action. Check out our documentation for more details.

Integration-created custom fields

Previously, it was not possible for integrations to create or edit custom fields in a workspace, they could only associate existing custom fields with projects. This was cumbersome, because setting up a custom field for your integration would require having a user set up the custom field for the integration, followed by telling the integration what custom field they just made.

We’ve now shipped endpoints to create and edit custom fields in our API to enable integrations to set up their own custom fields. Note that integration-defined custom fields exist in the workspace. Like any other custom field, users can change the definition of these fields. We recommend you use caution, avoid assumptions about the state of custom fields, and program defensively.

Project Memberships

Last year Asana added the ability to have team members in a project in comment-only mode to help keep tasks organized and less likely to be accidentally changed. We’ve released a new API resource called project_memberships to display this information. Now it’s possible to query directly if a user (or an integration authorized on the user’s behalf) has the ability to make changes to the tasks in a project according to access rules in Asana.

We’ll keep you updated as Asana’s API gets new features and modifications! To stay up to date with the latest news, be sure to subscribe to our developer newsletter via the form in the sidebar.

Start Dates & Other Changes - March 2018 API Updates

Start Dates Launch

Late last year, Asana launched Start Dates as a feature for Asana Premium. We’re happy to announce that start dates are now available via the API! As one of the fields you can set on a Task, the start_on field works exactly like the due_on field, where the date is specified in YYYY-MM-DD format.

For more on how start dates work in Asana, be sure to look at our documentation in the Asana Guide.

For more on tasks in the API, including the start_on field, see our API reference on Tasks.

Concurrent Requests Rate Limiter

In order to provide transparency on how we rate-limit incoming requests, we recently wrote documentation on how our rate-limiting works.

Of note is that recently, in addition to standard rate-limiting, we’ve also added in rate limits for concurrent requests. This will be particularly important for an upcoming release, so stay tuned!

Premium-Only Errors

Finally, we made changes to how we handle premium-only errors from our API. In summary, our API will return 402 Payment Required responses for requests that that originate from non-premium workspaces that attempt to access premium features.

We wrote about this extensively in another post, including our apologies for shipping this without communicating the change properly, as well as our migration strategy (and our recommended migration path for developers).

You can read more information about this in our errors documentation under 402 Payment Required.

Coming Soon

We have some features that we’re excited to launch in the next few weeks, so stay tuned! For keeping up with our latest updates, be sure to subscribe to our developer newsletter via the form in the sidebar.

Premium Only Error Changes in Asana’s API

Breaking Change: We’ve changed how we handle errors for premium-only features in the API, moving from HTTP 403 (Forbidden) to HTTP 402 (Payment Required). We are now using the new 402 error code for read requests and will be adding 402s to write requests on March 13th, 2018.


First, we want to apologize. A few weeks ago, we changed how we handle errors for requests that attempt to access premium-only features in a non-premium workspace. At the time we felt the change would be simple and for the betterment of our developers and our platform team, without being fully cognizant of how it would affect our developer community. We didn’t communicate broadly before the change went out, and many apps suffered failures as a result.

Furthermore, the change was meant to be propagated to both our read and write actions for our API, but due to a deployment issue, it only reached our API for read actions, whereas writes maintained the old behavior. We weren’t reactive enough to rollback immediately, and once several of our major developers started reacting and adjusting to the change, we decided to not cause further disruption.

We’re sorry for the pain and inconvenience this has caused, and after some soul-searching, we’re actively working on process changes to ensure that we:

  • Communicate breaking changes clearly, with plenty of time leading up to the change.
  • Add deprecation notices in our API responses, and communicate this process widely in our documentation.
  • Update our documentation accordingly throughout the entire process.

When we’ve finalized our deprecation process in the near future, we’ll be sure to write about it here, as well as extensively document our process in our developer documentation.

Premium-Only Error Change Announcement

As more features have been developed for Asana with a focus on Asana Premium, we’ve had to reconsider how we handle when an application in a non-premium workspace attempts to access a premium-only feature, such as Custom Fields.

Previously, the Asana API would return a 403 (Forbidden) response code, with a message containing “not available for free” in one of its errors in the JSON response body. Recently, we decided to change this behavior to return a 402 (Payment Required) instead of a 403 (Forbidden). We believe that by making this behavior consistent for our API endpoints in the future, it will be easier for developers to discern if the error is due to attempting to access a premium-only feature in a non-premium workspace, or if their application is unable to access an object due to permissions within Asana.

Preparing For The Change

On March 13th, 2018, we plan to make this change permanent for writes in the API; it is already in effect for reads. To prepare for this change, we suggest the following:

  • Add code to handle 402 error codes distinctly from 403 error codes.
  • To smoothly transition when we make the final change, in code that handles 403 errors, check the error message for the string "not available for free", and process these errors as you would a 402 error. This will ensure your code correctly handles write requests that return a 403 when payment is required (this will no longer be necessary as of March 13th).

All of the latest client libraries support handling the new 402 error code, both before and after the migration of our write endpoints to the new error code.

If you have any questions, feel free to reach out to us at api-support@asana.com. We’ll also have more announcements to make soon, so if you aren’t on it already, please join our developer newsletter via the form on the right side of this page!

Asana’s API gets more powerful with support for boards and sections.

Late last year, Asana released a new way to view tasks: Boards. When using a Board view in Asana, tasks show up in columns, with attractive displays of task cards and images that are easy to arrange in a visually pleasing way, and we’ve loved hearing the positive response for Boards!

We try to launch API features at the same time as their corresponding product features, but sometimes this isn’t possible, especially when the needs of integrations are slightly different and require different considerations than the needs of Asana users. We’ve been hard at work in Asana’s platform measuring how people use boards and characterizing some of the common ways that people might want to interact with them in our API, and we’re happy to announce that we’ve released the first version of our Boards API!

For people familiar with Asana, we’ve brought a idiom to our platform which can be used with both board and list views: Sections are a long-awaited, brand-new API resource which represent the section headers in a list view and the columns in a board view. In this way, code that does not need to know whether a project is a list or board view can use the “sections” property across both views of a project. For those integrations that do need to know if a project is a board or list view, the property “layout” has been added to our Projects resource to indicate board versus list views. Finally, we’ve added the capability to add and move tasks to a particular boards column by specifying it in addProject on tasks and to move sections to a particular place within a project. This lets integrations reorder individual tasks or whole columns in board views.

We hope you love it, and can’t wait to see what you build with Sections! For support issues, bug reports, or just to share your feedback, feel free to reach out to us at api-support@asana.com and let us know what you think!

You’re Invited! Asana’s new, faster platform

Asana has been investing in a faster infrastructure to make work tracking even more effortless, and this includes accessing information from our API. We have been focusing on the performance of our platform for months, and we’re now ready to show the world what we’ve accomplished! We’d love for you to check it out!

This new platform represents a completely rewritten server that provides data up to 5 times faster than before. We have been running tools to verify that the new platform behaves like our old one, so you should be able to migrate to our new API with minimal friction.

To make requests to our new API, all you have to do is add a HTTP header to your requests: Asana-Fast-Api: true. This will enable us to route your requests, if possible, to the new API. (The few requests that we are finishing up implementing in the API will be routed automatically to our existing API to provide the most seamless experience possible.) You can tell the difference between which version is handling your request by examining the headers of the response: if you receive the header X-Asana-Api-Version: 1.1, your request was handled through the new platform!

Here’s a cURL example, just to be clear:

curl -v --request GET -H "Authorization: Bearer $ASANA_PERSONAL_ACCESS_TOKEN" \
  -H 'Asana-Fast-Api: true' \

It’s as easy as that!

While it would be nice to be able to speed up everything in life by adding some “please make this fast” metadata, it wasn’t quite that simple for our team to get to where we are with the new platform. After a complete rewrite, including new tools and infrastructure to make sure we created a quality platform, we think this will be a great step forward, particularly for integrations which would like to use Asana in a more interactive way. This speed gain is intended to be more or less transparent to users of our platform, so there’s no reason not to try it out!

Of course, like all beta software, you may hit the occasional unintended hiccup. We’ve taken pains to try to faithfully replicate the behavior in our existing API with the new platform, but there are some slight differences: for instance, some error codes may have changed from 404 to 403, some authentication edge cases have been fixed, and so on. If you run into any major problems, feel free to join the conversations on our Slack organization Asana App Developers, channel #api_1_1_beta, or visit the Asana Community to get some help or give us your thoughts.


Matt Bramlage, Asana Developer Advocate

Using custom fields with Asana’s API

Now you can track anything in Asana with our newest feature, custom fields. With custom fields, users and integration developers can associate structured data with projects and tasks in Asana. The addition of custom fields enables new workflows in the Asana app and API. Most significantly, applications that previously had more limited data storage options can now store this data using custom fields.

Custom fields offer several advantages over the current ways of adding workflow-specific information to Asana tasks:

  • No special knowledge is required on the part of users.
  • Fields are visible to both integrations and users.
  • Fields specify structure with field type, and semantics are specified by the field’s name.
  • They provide an ideal interface between Asana and other applications.

Custom fields open new opportunities to use Asana with scripts and integrations, and we’re excited to see the many ways integrations can connect with Asana like never before!

No special knowledge is required on the part of users

Custom fields allow users of the Asana application to access and manipulate data in a way that is much more user-friendly and generalized. Previously, adding additional information to tasks that are outside the core set of fields that Asana provides would require users to know and honor rules about how the information was stored in the task. Now the user experience is much better. Rather than making users store information in a way that integrations can use, custom fields allow users to access customized information in a natural way.

Fields are visible to both integrations and users

Custom fields are visible and editable by both users and integrations, so it is possible for both to coexist and operate on the same data. Previously, to store arbitrary machine-parseable information in Asana without risking users breaking the integration required the “external” property on tasks. Of course, the downside is that this is not visible to users. This was more restrictive for enabling full interaction between users and integrations; these restrictions are now opened with custom fields.

Fields specify structure with field type, and semantics are specified by the field’s name

When managing data, it’s best to be able to infer both the shape or schema of the data and its purpose. The shape of the data allows programs to be able to bring information into a structure that they can work with, and the semantic purpose of the data helps define what that information represents and the actions that can be performed with it.

Imagine trying to store information about a referral in a candidate tracking project. It’s possible to store this information in the task description, but this is underspecified: there’s some information somewhere in a sea of text and integrations have to be built with parsers to extract this information before they can use it. A custom text field named “Primary Phone”, however, places a specified shape of data (a string) with a meaning (a phone number) in a place that makes the information both meaningful and manageable. It’s much easier for users and integrations to know what this information means and how it should be used.

Custom fields provide an ideal interface between Asana and other applications

We’re making Asana the best place to track and coordinate your workflows, and these flows can come from co-workers, other users, or other applications. Without custom fields, Asana didn’t always map to the information from external apps: when integrating with version control systems, for instance, where does the revision number go? The reviewer of a pull request can be assigned, but where does the author of the pull request go? What about classification of the pull request as a new feature or bug-fix?

With custom fields, there are many more possibilities for shaping Asana to fit the information from external sources than ever before. When writing an integration between a version control system, now it’s possible to have a dedicated text field for the revision number and author, an enum to classify the type of pull request, and other pieces of information.

In fact, this is exactly what our integration partner, Unito, has been developing with custom fields.

Unito and Asana/GitHub sync

Unito is an application that integrates and syncs information from various sources to smooth workflows and connect project management tools so that no-one is left out of the loop. Managing tasks in Asana and commenting on an issue in GitHub duplicates the information about the issue and creates more work to keep the information in both locations current. There’s much better efficiency when comments in Asana get applied to the GitHub issue, or GitHub commits and pull requests automatically show up in Asana.

Unito has built a connector to bridge Asana and GitHub to make this much easier. This connector uses custom fields in Asana for a variety of mappings from GitHub. For example, GitHub milestones can be mapped to a custom field named “Milestone,” so it’s clear inside of Asana what the context for tasks are. Mark a task as a duplicate, or as a bug or feature, and both Asana and GitHub will stay in sync as Unito manages the mapping and syncing between the two. We encourage you to sign up for Unito and try the integration to check it out for yourself!


A common request we receive is for an example that imports and exports data from Asana to an external database for later processing. So we built asana2sql, a tool which pulls information from Asana and stashes it in any sql-compatible database. This allows for offline access to Asana data for reporting, analysis, and offline processing.

Asana2sql was built to utilize custom fields. As a user of the Asana API, reviewing this project is a great way to see an example of how custom fields can be accessed. This is also a great way to contribute to open source projects that Asana provides to our community! If you’re interested in furthering Asana’s integrations and assisting other developers in getting started with Asana and custom fields, feel free to clone this project and submit pull requests for our team!

Custom fields are now available in Asana’s API. Go check out the Getting Started guide on custom fields to see how you can add more power and flexibility to your integration!

Asana is now deactivating TLS 1.0

TLS 1.0 is being deactivated across Asana’s services

TLS, or Transport Layer Security, is the successor to SSL (Secure Sockets Layer) in specifying a protocol for secure communications across the Internet. When connecting to a secure server (for example, sites with https addresses), TLS defines the set of methods by which a client and server can secure their connection. Defined in 1999, TLS 1.0 provided an update for SSL which revised the design and patched some vulnerabilities in the earlier protocol.

TLS 1.1, defined in 2006, contained revisions to the TLS protocol to further secure connections against some attack patterns which were found to compromise its security. This means that connections using the older TLS 1.0 protocol remain vulnerable to these attack vectors. As mentioned in an earlier post, it is for this reason that Asana has deprecated TLS 1.0 connections to our servers.

We are now rolling out this change. If you have an application that connects to Asana using TLS 1.0 or any version of the older SSL protocols, you can expect in the next few weeks to no longer be able to connect.

Most modern software, including both programming languages that use a library to connect securely and most popular web browsers, have been configured for quite some time to prefer newer versions of the protocol. If this is the case, you are already likely to be connecting over TLS 1.1 or 1.2. In this case, you will experience no change in your ability to connect to Asana.

If, however, you are using old and outdated software, or, as an OAuth integration developer, your users are using old and outdated web browsers, there is a possibility that your software may not support TLS 1.1 or 1.2. In this case, we strongly encourage you to be aware that this change is happening and to update your software as soon as possible to avoid service outages. As we turn off access to the Asana API, you will begin receiving 400 Bad Request responses, and, as always, we send a message back in the response body with more information about the error. This response will inform you that your TLS connection is out of date.

There are some situations that have been identified that warrant particular attention:

Mac OS X ships a very old version of OpenSSL which does not support TLS 1.1 and above. This means that, by default, software that links to libssl on OS X will likely be unable to connect to Asana’s API. Languages and libraries will have to be updated to link to a more modern version of OpenSSL, for instance, one installed using MacPorts or Homebrew. We are currently updating information about how to do this for each language in the documentation for our client libraries:

Salesforce has constructed a table of guidelines for software that is and is not compatible with TLS 1.1 and higher. In general:

  • Google Chrome version 38 (Oct 2014) and newer is compatible by default across all operating systems. Version 22 (Sept 2012) to 37 are compatible when running on modern operating systems, for example Windows Vista and Mac OS X 10.6 and newer. Version 21 and older are not compatible.

  • Firefox version 27 (Sept 2013) and newer is compatible by default. Version 23 to 26 are compatible, but must be configured to use TLS 1.1 and higher. Version 22 and older are not compatible.

  • Internet Explorer version 11 (Oct 2013) and above is compatible by default. Versions 8, 9, and 10 are compatible on Windows 7 and newer, but must be configured to use TLS 1.1 and higher. Internet Explorer 8, 9, and 10 on Vista and older, and Internet Explorer 7 and older, are not compatible.

  • Programming languages and libraries vary, but in general, languages and libraries that have been updated within the past few years will be compatible. In particular, note the information about OpenSSL on OS X above. Salesforce’s table covers the versions of several modern languages quite thoroughly.

Update: A temporary workaround: amnesty headers

It’s very difficult for any organization to introduce a breaking change to their API. As long as nothing is breaking, there’s not much of a reason to take a look at, for instance, deprecation headers (though that’s a good practice); and after things are breaking, integration developers are stuck working with a zero-day break in the API. Neither case is ideal here: either developers never migrate off of old APIs that we want to expire, or we put them in an emergency state.

Here at Asana, we really don’t like those choices. We’ve been thinking about how to deal with this for a while, but the TLS deprecation change had a broader impact than we anticipated, and so we think it’s a good time to release a glimpse of what we’re thinking of doing in these cases.

For fixing breaking changes, here’s what we’re going to try:

  1. Begin returning a deprecation header when we identify requests that will break in Asana’s API. This header will only be returned on requests that will break when we introduce the change. In other words, if you see this header, your existing API call is on its way to being broken in some way. We’re currently working on what this header will be called and what it will contain.
  2. At the same time, we’ll return an Asana-Amnesty-{topic}-Expires header with a HTTP RFC 1123 date format, which is the same format that the standard HTTP Expires date is in. More information about this below.
  3. Send out a developer newsletter (and contact developers through other channels) to let them know there’s a deprecation in the API.
  4. After some time, we’ll introduce the breaking change at a low-level of errors. For instance, return a 4xx error for 10% of all requests. This error will both include the above headers and a descriptive error message in the response. The goal here is to provide significant feedback about changes occurring in the API, without completely disabling it, for developers who didn’t notice or haven’t had time to implement changes that mitigate the deprecated feature. Since the requests can be retried, even though there will be a significant number of errors being returned by the Asana API, developers who have written robust integrations with retries should still see eventual success.
  5. When we introduce the low-frequency breaking change, we’ll also start handling a request header: Asana-Amnesty-{topic}. Setting this header to true will enable requests to be served on a temporary basis without the 4xx error codes. This header can be set before the breaking change happens in order to ensure a completely smooth transition; the net effect will be that no breakage will occur.
  6. Increase the frequency of the breaking change over some time until the change is in full effect - that is, 100% of the requests without Asana-Amnesty-{topic}: true will fail with a 4xx error code.
  7. When the date in Asana-Amnesty-{topic}-Expires passes, we will no longer accept Asana-Amnesty-{topic} headers. At this time, all integrations which use the old behavior will be broken.

We think this provides the best possible experience for integrations developers, while allowing us to remove, for example, less-secure connections via TLS 1.0 to our API. There is a workflow that allows preemptive immunity to our breaking changes, that is, catching deprecation headers and preemptively setting the amnesty header, while still allowing Asana to implement a migration path and remove old ways of interacting with our API.

So, at this time, if the header Asana-Amnesty-Tls: true is passed to Asana’s API, we will still honor your request without returning a 4xx error code; but please note that this is a temporary measure, and we will stop accepting TLS 1.0 requests entirely on Wednesday, September 14, 2016.

This change is an important step to ensure the security of our users’ data, and we appreciate your participation. Thanks for helping us keep our users safe!

Matt Bramlage, Asana Developer Advocate

Deprecation of OAuth 2.0 ‘http’ Redirects

Deprecated: OAuth redirects to http servers

At Asana, we take the security of our users seriously. Last fall, we deprecated connecting with Asana via an API key in favor of OAuth 2.0, which is a reliable method for providing safe authentication to apps which connect with Asana. We will make a additional change soon to make our OAuth workflow even more secure by requiring that applications which connect to Asana via OAuth use an encrypted connection for the entire authentication workflow.


The OAuth workflow, which you can read up on at our developers documentation website, involves users temporarily visiting a location on Asana’s servers to authorize access to third party applications. Once the user has verified the permission of the app to access their data, Asana’s servers redirect the user back to the third party app with information that can be used by the application to make API calls to Asana’s servers. This redirect is the step that we are making more secure.

If an Asana integration app is using an unencrypted redirect address (where the url begins with http) as their callback location, it’s possible for a third party to catch the plaintext information that Asana is returning and use it to impersonate the application. Rather than redirecting to a server that is expecting an unencrypted connection, we are making the entire workflow happen with SSL/TLS encryption. This means that all redirect URLs for integrating apps must redirect to a secure server which uses https as its scheme.

Asana will soon disallow new application registrations which use unencrypted connections for redirect URLs. In addition:

In mid-August, we will begin refusing redirects to existing applications which use http.

How to make the change in Asana

Asana will soon disallow new application registrations which use unencrypted connections for redirect URLs. In mid August, we will enforce the new redirect behavior If you have an existing application that may be using an unencrypted redirect, please check your application settings to ensure you are returning to an https address during the OAuth authentication process. You can check your settings on the Developer App Management page. Follow this link to your Account Settings dialog or click your picture in the Asana application and navigate to the “My Profile Settings” link, where you can find the “Apps” tab. At the bottom of this tab there is a link to “Manage Developer Apps” Click on the name of your application under the “Apps You Own” heading to double check its settings.

Manage Developer Apps link

The field that will require checking is “Redirect URL”. If this field begins with “http”, you will have to implement the changeover to https.

Redirect URL field

How to make the change on your server

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 you should secure your server by purchasing a certificate from a certificate authority. A short summary of the steps for each of these processes can be read here.

Your application will need to be configured to accept SSL/TLS connections, 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.

This change will ensure that all of our users can continue to use Asana and our partner integrations securely. We appreciate your support and help! If you have any questions or feedback, you can contact the api team at api-support@asana.com for assistance.


Matt Bramlage, Asana Developer Advocate

Webhooks Launch and Custom Fields

Launched: Webhooks!

We’ve formally launched webhooks! Since the release, we’ve found that many developers are already getting a lot of value out of webhooks. You can read about how Slack, Unito, tray.io, and Instagantt are using webhooks in our recent blog post. To learn more about webhooks, or get started using them, check out our Developer’s page.

If you try out webhooks, we welcome your feedback at api-support@asana.com. The top request so far has been for more granular event information, which we are looking to implement next.

In Beta: Custom Fields

We’re excited to share that our new custom fields feature is currently in a private beta. This release of custom fields is the first step toward enabling customers to track anything in Asana. With custom fields, Asana users can track and categorize information specific to their team’s needs. Users can create their own fields like priority level, billable hours, deal stage, and much more. In the long term, custom fields will make Asana a more powerful tool for our users, integration partners, and our developer community.

We’re looking at opening up the beta to a broader audience over the coming months. Sign up here if you’re interested in using custom fields!

In Progress: Performance

A major focus right now at Asana is performance, and that extends to our API. Our API team is working on dramatically reducing the latency of API requests. To do so, we’re building a brand-new API server on top of our LunaDb datastore.

We’ll likely roll out these changes on an endpoint-by-endpoint basis, focusing first on GET requests before moving on to POSTs and PUTs. We intend to maintain backwards compatibility in most places, although we may fix a few bugs between versions along the way.

Security Update: Deprecating TLS 1.0 Support

In our continuous efforts to improve data security, we will be disabling TLS 1.0 across Asana services starting in September. This will prevent clients limited to TLS 1.0 from accessing the Asana API for inbound and outbound connections.

TLS (Transport Layer Security, the more modern version of SSL) ensures that your application is connected to authentic Asana services and prevents attackers from snooping on your connections. Asana web, mobile, API, and email delivery use TLS as a key component of their security, but TLS 1.0 is an older and more vulnerable version of the protocol.

Before TLS 1.0 is disabled, you will need to ensure that TLS 1.1 or 1.2 is enabled for your application’s integration with Asana. You can consult Salesforce’s thorough compatibility overview to see if your integration is affected. Consider this for both inbound and outbound connections (including OAuth and webhooks).

API Key Update

As noted in our previous newsletter, we are deprecating the API key authentication mechanism for our API in November 2016. Any applications using API keys after this time will stop working. If you haven’t done so already, here are ways you can replace API keys:

  • Personal access tokens: These are an alternative to API keys for command-line or script access, personal projects, or rapid prototyping of applications that will implement OAuth.
  • API key to OAuth migration: This is an endpoint for applications currently deployed using API keys to exchange those keys for OAuth credentials.

Note that new Asana users can no longer generate API keys. If you have deployed an application that requires an API key, you will be unable to accept new users, and will need to replace API keys using one of the methods listed above.

Webhooks Beta


Update 12 April 2015: Webhooks are no longer in beta - they’ve launched!

Our team has been hard at work building Webhooks, and we’re opening it up to interested developers to beta-test before we do a full launch!

Webhooks provides a way for you to tell Asana to make HTTP requests back to your server whenever data in Asana changes. You may wish to try it if your application wants to respond to “events” in Asana, like task changes or commenting.

Here are some examples of how you might use Webhooks:

  • Post a comment in a chat room every time a task in a certain project is added.
  • Reflect new comments in Asana into another system, like a bug tracker or CRM tool.
  • Show a real-time ticker of the most recently completed tasks.

To learn more and start using the feature in beta, read our documentation.

We’d love to hear your feedback! You can tell us what you think by sending a note to api-support@asana.com. We’re particularly interested to hear whether you find the feature easy to use and whether it meets the needs of your application.

While our implementation is currently stable, it is possible that we’ll make changes based on feedback before our public launch. So, please be aware that if you use the beta version, you may have to make some adjustments to your implementation when we launch it for real.

More API Key Deprecation Details

More API Key Deprecation Details

See our API Key Deprecation article for more background about our upcoming removal of the API Key as a means of authentication.

On January 20, 2016, new Asana users will no longer be able to generate API keys. Here are a few things to keep in mind:

  • This means if you have deployed an application that requires an API key, you will be unable to accept new users.
  • Users with existing API keys will be unaffected by this change. This means all apps will continue to work for all their existing users.

In 4-6 months, Asana will no longer accept any API keys to authenticate.

  • If you have an application that still uses API keys, it will stop working.

Redesign & User Management

New Asana assets

We’d appreciate your help in updating any existing Asana assets on your properties to our new style. Our new logo, updated screenshots, and brand guidelines can be directly downloaded from our press page.

If you currently include a company description about Asana on any of your properties we’d appreciate you updating it to the following:

Asana is the easiest way for teams to track their work. From tasks and projects to conversations and dashboards, Asana enables teams to move work from start to finish—and get results.

User Management

We recently released a few API endpoints that allow for easy user management through the API. Invite new members to an organization or add them to a team; administrators can even remove a user from an organization with a simple API call!

Head on over to our API reference documentation on Teams and Workspaces to see the endpoints we have added. Also make sure to check out the sample application that demonstrates how these endpoints all work together!

API Key Deprecation

API Key Deprecation

The Asana API key has served as a low barrier to entry means of authenticating against the API. We created it for personal scripts or for rapid prototyping of applications. Applications intended for large scale deployment should implement Asana Connect (OAuth 2.0) for authentication.

While easier to get started with, the API key poses security risks and provides a degraded user experience overall. Because we care deeply about user experience and security of the platform, we are rolling out a deprecation plan for API keys. This means that in the future, these keys will no longer be an acceptable means of authentication and developers will need to migrate to using one of the options below. We understand this will generate work for some developers and we’ll do our best to ease the transition to what we strongly believe is a more secure and robust developer ecosystem.

API Deprecation Timeline

  • Today - Asana will launch personal access tokens (an alternative to API keys for command line access, personal projects or rapid prototyping of applications that will implement OAuth).

  • Today - Asana will launch a migration mechanism for applications currently deployed using API keys to exchange those keys for OAuth credentials.

  • January, 2016 - Users will no longer be able to generate new API keys.

  • January, 2017 - Asana will no longer accept API keys as a means of authenticating to the API without an amnesty header.

  • February, 2017 - Asana will no longer accept API key amnesty.

Amnesty Headers: A temporary workaround

When we make a breaking change to the API, we strive to use various channels to inform developers and also provide sufficient time for them to make the necessary changes. Despite our best efforts, we understand that some developers will miss or ignore deprecations until something breaks. To help these developers quickly get unblocked while they migrate to OAuth or PATs, we will provide temporary amnesty.

To request amnesty, set the API key amnesty header to true: Asana-Amnesty-Api-Key: true. Setting this header to true will enable requests to be served on a temporary basis without the 434 error code. We will stop accepting Amnesty headers in February, 2017.

OAuth Migration

In preparation for deprecating the API key, we’re providing a migration mechanism from API keys to OAuth authorizations for applications that have previously relied on API keys. If you have a service that operates for multiple different users, it should leverage Asana Connect (Oauth 2.0) for authentication of those users instead of individuals’ API keys or personal access tokens.

This migration mechanism is actually quite simple—head over to the documentation to learn more and if you have any questions please send us a note to api-support@asana.com.

Personal Access Tokens

With deprecating the API key we still want to provide a low-friction way to access the Asana API for writing scripts, prototyping an application or working on the command line. Personal access tokens do just that and more! You can create a personal access token for yourself on the “apps” tab of your profile settings.

Be careful—these tokens should be treated like passwords. The advantage to personal access tokens over API keys is that you can create many and revoke them on an individual basis when they’re no longer needed. You’ll need to enter a description for each token you create to help you remember its purpose if you ever decide that you want to revoke it.

Client Libraries, API Explorer, & Changelog

Client Libraries

We’ve released several new client libraries to make development on the Asana platform as smooth as possible for you, regardless of which language you develop in. These libraries will stay up-to-date as the API develops new features and functionality.

Each library is hosted on GitHub, so we encourage you to contribute and log issues on each repository. Note that we would like to hold each client to a similar structure to increase maintainability.

API Explorer

We recently launched an API explorer on the developer site to help you rapidly explore the API. Once you authenticate with the explorer using your Asana credentials, you can use it to make GET requests to the API on your behalf. The explorer is a client-side OAuth application written in typescript using the React JS framework. We have open sourced the entire application so you can see how it works for yourself!

API Changelog

As the API continues to develop and we refine the documentation, we want you to stay as updated and informed as possible. API Changelog monitors our API documentation and can send you a notification when it changes. Subscribe to change notifications.

Hearts, recent tasks, and more!

We are happy to announce a few changes to the API that you may or may not have noticed:

  • Hearts are now included by default in both tasks and stories. Hearts can be queried using the new parameters: hearted, hearts, and num_hearts. You can read more about this in our documentation on tasks and stories.
  • Recent tasks. You can now query for recently completed or modified tasks using the new completed_since and modified_since parameters. You can read more in our documentation.
  • User avatars can now be queried with or without specifying a specific photo size. For example, ?opt_fields=photo returns all possible photo sizes, and ?opt_fields=photo.image_128x128 returns one specific photo size.
  • Email visibility. We’ve fixed a small bug where we threw an error when querying for a user’s email that was hidden due to insufficient permissions. Instead, we now return the results and use null for the user’s email.s