Asana is moving to string IDs [Updated with revised timeline]

Thanks all for your prompt responses!

@Joe_Trollo, that makes it very clear. I’m assuming the settings apply only for that session and for a new session, if I don’t send in the header, the behavior will fallback to default, i.e. receiving both integer and string IDs. Also, would you advice we wait till your implementation is 100% before performing any further tests?

If you set the headers on the client directly, they will apply to every request made with that client. If you pass them in the method call, they will apply only to that one request. Clearing the header from the client or not including them in the method call will then fall back to the default behavior, yes.

To be more explicit about the gap in our implementation: we have 100% coverage on read and write requests in the API (enabling this feature will hide numeric IDs on reads and reject numeric IDs on writes) but do not yet have support for requests that originate from within Asana (i.e., outgoing webhook payloads). If your app does not use webhooks, you can freely test the rest of the API, but we won’t be starting the clock for the deprecation until the entire API supports string IDs.

Got it. I’ve successfully tested switching the integer ids on an off - thanks!

Hi everyone! After a disappointingly large technical hurdle, we’re finally able to begin this deprecation! To recap:

  • This deprecation will operate under the name "string_ids" and can be enabled by sending an Asana-Enable: string_ids header in your requests
  • When this deprecation is enabled,
    • The API will not provide a numerical "id" field for any object in the response, and you will only receive the string "gid" field
    • The API will not accept numerical IDs in any part of the request
      • URLs and paths are already always strings and do not need to be changed
      • Form-encoded key-value pairs don’t have type information and are already always strings, so they do not need to be changed
      • JSON bodies do have type information, and you’ll need to change the fields in your request bodies from things like "projects": [123, 456] to "projects": ["123", "456"]
  • There are new settings to control the format of webhook bodies
    • The webhook objects themselves have an "always_use_string_ids" field on them which you can change to migrate individual webhooks into the new format
    • Each app in your developer console will have options for migrating the entire app as a whole (screenshots below)
    • Refer to the table in my previous post for specifics on how these two settings interact

Here’s what the app option will look like in the developer console:

On the matter of the timeline:

  • You can begin the deprecation starting today. The new options in the developer console will be gradually rolling out over the next week or so.
  • The “activation date” (the day on which string IDs become the default behavior) will be August 13th, 2019
  • The “end date” (the day on which string IDs become permanent) will be February 11th, 2020

As always, let us know if you have any questions about this deprecation. Because of the scope of this deprecation, we’ll be monitoring the situation closely as developers migrate their apps.


The new options in the developer console have now been rolled out to 100% of users.



I am trying to send the header Asana-Enable: string_ids from the official PHP client library

Can you provide an example on how this is done? Thank you very much.

Hello all, we have an important update to share about the timeline of this deprecation.

Because this deprecation affects literally every API request and webhook, there’s a risk that we will cause a large number of heavily-used apps to encounter errors for extended periods of time if we change the default behavior in an instant on the activation date. In fact, in the last month, nearly 7,000 apps with over 230,000 users have not opted in or out of the deprecation and will almost certainly break when the deprecation is activated on August 13th.

To mitigate this, we will make changes to the default behavior in three steps:

  • August 13th, 12:00 pm PDT — we will change the default behavior from inactive to active for five minutes, turning it back to inactive at 12:05 pm. This will cause errors for large, heavily-used apps and prompt their developers to begin investigations. By only staying enabled for five minutes, we ensure that these apps are not broken for several hours or several days while their developers learn about the deprecation and try to adjust for it. (Updating code and tests to use the deprecation framework and opt-out can take significant time for large apps with complex deployments.)
  • August 20th, 12:00 pm PDT — we will change the default behavior from inactive to active for one hour, turning it back to inactive at 1:00 pm. Assuming the largest apps were caught by the previous event, this will catch the next group of apps, such as those that may not make requests more than once per five minutes.
  • August 27th, 12:00 pm PDT — we will change the default behavior from inactive to active and keep it active. From this point on, old behavior will only be accessible through sending an Asana-Disable: string_ids header to opt-out.

Please let us know if you have any questions or concerns about this timeline.

1 Like

Wow. BUT maybe it won’t be quite that dire - perhaps (hopefully) other apps are in the same boat as Flowsana: because you started passing “gid” alongside “id” many months ago, I switched to relying on “gid” for my IDs a while back. That means that I’m compatible with the new string-ID model (except for webhooks) without having to opt in or out.

"except for webhooks"
Well, OK, true, my hopeful optimism doesn’t apply to webhooks - for apps that use those and didn’t opt in or out, their webhook code will break on August 13th. (I just updated mine today, will be testing it this coming week and putting it into production next weekend.)

And I’ve converted Asana2Go this past weekend so your outstanding list is down to 6,999 now!




Hello all, I have a last-minute update about today’s scheduled “bump.” Because we are currently experiencing downtime, we will not be changing the default behavior today. We will instead be having the bump tomorrow, August 14th from 12:00 pm to 12:05 pm PDT. Sorry for the sudden change, but we are concerned that developers may attribute string-ID-related errors as fallout from the downtime and thus ignore it.