[Change] API token formats are changing

English Forum Developers & API Changelog
, ,
1

What’s new

Asana will start generating API tokens in an updated format. Token formats will have no functional impact on the API response and any existing valid token will continue to work with the API. No action is needed to ensure existing tokens continue to work as expected.

Note on token formats

Opaque tokens
Asana API tokens should be treated as opaque. Token formats may change without notice. Validating a token’s format on the client side could result in unexpected breakages. For this reason, we are not listing any specific changes being made to the format.

Encoding special characters
Asana API tokens may contain special characters which need to be URL encoded if you are submitting a token in a form-encoded request body. This is relevant for OAuth token exchange or token revocation endpoints. We recommend using a library or a built-in utility function in your language.

This applies to any and all Asana API tokens including:

  • personal access tokens
  • service account tokens
  • OAuth
    • refresh tokens
    • access tokens

Who is Impacted

You might be impacted by this if:

  • Your application applies validation to ensure Asana API tokens are in a certain format. This is not a recommended practice (see above).
  • You are not URL encoding a token as part of a form-encoded request body (or encoding it in a way which expects special characters in a certain position).

Reasons for the change

As Asana makes changes to its infrastructure, we may change the token format from time to time in order to more efficiently serve API requests.

Timeline

Token format changes will gradually be rolled out and you may see format changes as soon as this week.

5 Likes
2

I completely get this. However, one thing I think you do need to let us know is if the maximum possible length of a token is changing, for those of us who store tokens on our end.

Based on discussions with Asana DevRel when I first created Flowsana, I set my token database field length to 400 characters and my refresh token field length to 200 characters. If either of those is no longer going to be long enough, I need to know so I can increase those field lengths ASAP.

Thanks, @John_Baldo!

1 Like
4

Updated this post with additional information on special characters.

@Phil_Seeman , sorry for the delay, but for token length… the token length should increase but should fall within those limits. We can be mindful of the length when introducing future changes. OAuth access tokens currently have the longest and variable length, but also expire after 1 hour.

1 Like