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' \
  "https://app.asana.com/api/1.0/tasks/$TASKID"

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.

Thanks,

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!

Asana2sql

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.

Background:

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.

Thanks,

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

Webhooks

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.

API Change to Cookie Auth

Keeping users’ data in Asana secure is our top priority. We learned of a potential security threat when apps piggyback on a user’s cookie for authentication, so we are disallowing that authentication method.

We don’t make this decision lightly and understand how important it is to keep our API stable. We apologize for the difficulties this may cause you.

If you have been relying on the user’s asana.com cookies for authentication, please update your apps to use OAuth or API keys, as described in https://asana.com/developers/documentation/getting-started/auth

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

File attachments, colors, CORS and more!

We have a few new (and in some cases, old-but-we-didn’t-mention-yet) features to draw your attention to:

  • File attachments. You can both fetch and upload file attachments to tasks, see the documentation on Attachments for more details.
  • User avatars are now included in the user object, see the documentation on Users for the new photo property, which maps different sizes to URLs.
  • Delete projects and tasks. Using the DELETE verb, you can now delete projects and tasks. Pretty straightforward.
  • **Fetch archived tasks. By including ?include_archived=true in a request for tasks in a project, you will now also receive the archived tasks in addition to the unarchived ones.
  • Colors! You can now both request and set the colors for projects and tags, through a new attribute creatively dubbed color, which can be null or a string encoding a color. Valid colors are:
    • light-yellow
    • dark-brown
    • (light|dark)-(pink|green|blue|red|teal|orange|purple|warm-gray)

Note: colors are specific to the user, rather than global, so if you set the color as one user you won’t see it reflected as another.

  • CORS support. For those of you building in-browser apps, this will be a nice addition: you can now make requests to the Asana API, including POST/PUT/DELETE, from other domains (as long as it’s a reasonably modern browser). See this gist for an example of how to use this feature.

Organizations, JSON-P, and more!

We just wanted to call your attention to a few changes to the API that you may or may not have noticed if you’ve been developing with us for some time. Some changes we rolled out just recently, others a little while ago:

  • Organizations. With the introduction of Organizations, we’ve updated the API to handle the changes to how your data is organized. These changes are very minor, but could impact you if you’ve upgraded. The main change is that in Workspaces that have been upgraded to Organizations, when you create a new Project via the API you must specify a team to put the Project in.
  • JSON-P support. If you authenticate using Asana Connect, you can now make requests to the API and receive a response in JSON-P format. Simply add the URL parameter opt_jsonp=CALLBACK, filling in the name of the function you want in place of CALLBACK, and that function will be called with the result. Update: JSON-P support has been deprecated.
  • Task ordering. You can use the insert_before and insert_after parameters on the addProject Task endpoint in order to insert or move a Task to a specific place within the Project.
  • Subtask re-homing. You can set the parent field on a Task to change which Task it is a subtask of.
  • Followers. The addFollowers and removeFollowers Task endpoints allow you to add or remove followers on a Task.

We hope these changes are helpful, and as usual give us feedback at api-support@asana.com!

Asana Connect

We’re announcing a new feature for the API today: Asana Connect!

Asana Connect uses OAuth 2.0 to authenticate users, so you no longer have to ask them to supply an API key. There’s plenty of documentation, some example code, and even a ruby gem for omniauth.

This was an extremely popular request, so we’re looking forward to seeing lot of “Sign in with Asana” buttons. If you hit any problems, be sure to let us know by reporting issues (or feedback) to api-support@asana.com!

Add to project during task creation

In addition to fixing a few bugs lately, we’ve also allowed you to specify a projects field during task creation, and provide a list of ids of the projects the task should be added to. This has been updated in the Task reference documentation.

Tags are here!

Thanks to all those that requested it, the API now supports tags! Here are the changes we recently rolled out:

  • Projects now have a stories endpoint similar to tasks, for querying comments/updates on the project object itself.
  • There is a new /tags endpoint for manipulating tags.
  • Full records for tasks now include a tags field.
  • The task endpoint now has addTag and removeTag methods.

Minor bugfixes

We’ve fixed a few bugs in the last week, including:

  • The “method” option was ineffective when using it in the POST body.
  • 500 error when setting a task assignee to null.

Just a reminder to our developers that if you receive a 500 response, you’ve probably hit a bug in the API. Please don’t be shy about reporting it to api-support@asana.com!

Version 1.0 of the API has launched!

We’re pleased to announce that the first public version of the Asana API is live!

Existing developers should take note of an important change. The base URL for all API requests has changed to:

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

Notice we have changed the version number and removed the leading dash (-) from the path. We will keep the old 0.1 access point around for a while and give you time to switch over, but will end-of-life it soon. Please update your clients!

Thanks for being a part of our early access program. Happy developing!

Minor fixes, changes and additions

  • Fixed a bug where requests that should return 400 were returning 500s or unparsable content.
  • Renamed Task.schedule_status to assignee_status and changed its value of ok to later
  • Added Task.due_on so you can get and set due dates for Tasks with the API.

First API Update

  • Discarded opt_include/opt_exclude in favor of just opt_fields which explicitly names all fields desired. Any unnamed fields will not be included in the output (we think this is the right way to expose this functionality, so you don’t have to guess what will be included by default.) The ID of objects are always included.
  • Added a (read-only) “workspace” property to Tasks.
  • target and source of a Story are no longer part of their compact representation.