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

I finally got it working by adding a hack to send the Asana-Disable: string_ids header. I am still having no idea what needs to be done to make the php-asana (the official one) client use the string based id’s. I hope/assume whoever works on the php-asana library is aware that it’s broken and will be working to fix it before the Asana-Disable hack goes away.

And to be clear, my beef was less that a change had to be made, and more that it got made right before a long weekend.

Hello all, I have a rather unfortunate update.

Sometime between when we did all the engineering and testing work for string IDs about 10 months ago and when we activated the string ID change this past month, we introduced a bug in our configuration. This impact of this bug is that only some routes and features of our API are excluding numeric IDs by default. In particular: webhooks, event streams, and PUT/POST routes now exclude numeric IDs from their responses. Meanwhile, the rest of our API is still returning the id field by default if you haven’t opted out of the deprecation.

This means that we still have half of this deprecation we need to activate, and it actually accounts for a lot more than half of the API and its traffic. If you are not using the deprecation headers, your app is operating in a half-old, half-new world and there is still a very large possibility that it will break with the next activation. Once again, to mitigate the impact, we will “bump” the API for a short period of time to help apps discover incompatibilities without breaking them for too long. The schedule for the remaining rollout is as follows:

  • September 17th, 10:00 am PDT — we will change the default behavior from inactive to active for two hours, turning it back to inactive at 12:00 pm. We will be monitoring the impact from this “bump” through a number of channels. Depending on the magnitude of the impact, we may postpone the final activation.
  • September 24th, 10:00 am 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 by sending an Asana-Disable: string_ids header to temporarily opt-out.

To summarize, you will fall into one of these three categories and should take the recommended action:

  • If you have already opted in or out by passing in deprecation headers, you have no further action to take.
  • If you have changed your code to leverage string GIDs but are not sending headers, please check that you have applied the changes to your code using our read endpoints as these have still been providing numeric IDs.
  • If you haven’t yet taken action on this deprecation, your app may already be malfunctioning, so please modify your app to use string GIDs or delay the deprecation by opting out by sending an Asana-Disable: string_ids header.

Some background about the bug and its discovery

Background: The API has a “live” configuration that, when changed, will immediately be reflected in the active API deployments. In this configuration, we list out all the ongoing deprecations and whether they are enabled by default. This is actually a list, too, and not a mapping. These are the settings we change on the start, activation, and end dates for deprecations. There is also a “base” configuration that is used as a fallback for things not specified in the live configuration. The final configuration is determined by taking the base configuration and “merging” it with the live configuration, overwriting appropriate keys.

Additionally, those of you who have been around for a while may recall that we rebuilt our API to improve performance. Due to internal technical limitations, we unfortunately have to maintain both the new and old systems. The old handles webhooks, event streams, and writes of data, while the new handles reading data.

Bug: The old system (which was correctly activated) read default values for our deprecations, and then completely replaced the list of settings with the live configuration. The new system read the default values, and then extended that list with the live configuration. This led to a final configuration that was akin to deprecations: ["something else", "string IDs are off by default", "another thing", "string IDs are on by default"]. (We don’t actually use a list of strings like this—we’re not monsters!) When we later used this list to determine what the default behavior should be, we took the first matching setting in the list, which indicated that string IDs should not be activated.

Discovery: I was making some manual API requests to debug a script I was creating, and was not bothering to pass any deprecation headers. I then noticed in the responses that the id field was still being included, which kicked off the investigation.

Remediation: We will be changing our configuration parsing to assert that no deprecation appears twice in the final list of settings.

Thank you for your patience as we try to roll out this especially difficult deprecation! Please let us know if you have more questions or concerns.

Thanks a lot for the detailed answer, really interesting! Good luck on the fix.

Hello all,

Upon assessing the fallout from the most recent “bump” (which properly affected the entire API) we have decided that changing the default behavior across the entire API tomorrow as scheduled would negatively affect far more of our users than we’re comfortable with. As such we are cancelling tomorrow’s activation and are updating our schedule with the following dates:

  • October 15th, 12:00 pm PDT — we will change the default behavior from inactive to active for 24 hours , turning it back to inactive at October 16th, 12:00 pm.
  • October 29th, 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 by sending an Asana-Disable: string_ids header to temporarily opt-out.

I apologize for this additional churn as we try to balance ease of migration for developers and impact for Asana users.


Thanks for the update, good luck :wink:

Right? I just read and felt like… ohh man you don’t have anything better to do than making us redo all our stuff?


This is actually a pretty minor change in the code, replacing id with gid and update typings :slight_smile: Did you manage to do it?

wow, minor… Visual Studio just sticks to 99+ references to ‘id’ and a long and string behave differently, e.g. id = 0 vs id = string.empty or similar.
oh, then there’s the database changes… sad times.
I think this is going to cost upwards of £3k in dev time alone… now to test…

Is there an update for the Node client? client.headers doesn’t seems to work here. I can’t find anything about this in the docs nor the wiki from github.

Here is a sample that used to work

this.client = Asana.Client.create({
      clientId: environment.asana.clientId,
      redirectUri: environment.asana.redirectUri,
      defaultHeaders: {'Asana-Enable' : 'string_ids'}
1 Like

Hello all, I have a short update here: due to an internal issue, we are not enacting this change today. We are monitoring the situation and will reevaluate tomorrow, targeting noon PST again. Sorry for the delay!

Hey Joe, is this a correct posting? What change is this referring to?

Confused in DC

Joe can correct me if I’m wrong, but I believe this is removing the opt out option for string ids. If your app is sending the asana-disable: string_ids header, it will stop working tomorrow. I believe we emailed the apps that are doing this (that we had working emails for).

1 Like

@Ross_Grambo is correct. Today we were scheduled to permanently enable the string_ids deprecation, such that apps could no longer opt-out and keep getting numeric IDs. Sending an Asana-Disable: string_ids will no longer have any effect after we make this change, which we will revisit enacting tomorrow.

1 Like

We resolved the issue and as of noon PST yesterday, the Asana API no longer supports numeric IDs. It’s been two years since we started planning this deprecation and 18 months since we first published communications about it. Thank you all so much for your patience and understanding throughout this tedious and complicated migration!


:champagne: :champagne: :champagne:


Hello @Adam_Lambert,

I’m in charge of the PHP Client Library. I created a new post for us to talk about your issue, as I believe it’s more client library related than general string id related. Lets talk on that post.

Hi Ross,

  Believe it or not, I got it sorted out between when I posted that

and now. In summary, the switch to GID created two problems for

  1) I had to go locate the project GID's the replaced the old

project ID’s, as the GID’s were not the same numbers. This I did
back in 2019 when the first round of changes broke all my client
side code. But using the GID’s instead of the ID’s didn’t solve
anything - it all still failed for me. So back in 2019 when all
that was going on, I finally gave up and added the header to
ignore the gid thing (forget the exact syntax - but that worked)
and carried on with the code as it had been working at that time.

  2) The change yesterday, of course, broke it all again.  This

time, no headers to fix. So, I grabbed a fresh copy of the PHP
client library, and … still no joy. After beating my head
against the wall for a while, I went and whined in the forum.
Then of course, about 20 mins later, I finally got it working.

  Anyway - to cut to the final point, prior to the GID thing, this

code used to work with the project ID. And replacing the project
ID with the GID did not work.

  $Task = $client->tasks->createInWorkspace(12345678910,

$blahblah); // where 12345678910 was the project ID or the
project GID either one.

But this code does work:

  $Task = $client->tasks->createInWorkspace("12345678910",


  Because without the quotes, it gets interpreted as an integer

value, which Asana rejects (or at least that’s what I think the
deal is).

  Anyway - not a problem with the library - problem with me not

being a particularly sharp programmer (I’m not actually a
programmer at all, but I ended having to mess around with this
stuff to automate task creation due to the volume of tasks I need
to create on a regular basis).



Oh cool! Happy to hear! You’re more than welcome to reach out if you hit a different issue! :slight_smile:

1 Like