[ Change ] GET /projects, GET /users, and GET /tags will require a workspace or team

English Forum Developers & API Changelog
, ,
1

Summary

  • The GET /projects, GET /users, and GET /tags endpoints will soon require a workspace or team parameter when making requests for users who belong to multiple workspaces. Cross-workspace fetching will be deprecated.
  • Workspace-scoped requests are an established pattern in the Asana API that we are expanding to improve performance for most clients (which are only interested in data for a single workspace).
  • Fetching data for multiple workspaces will still be possible, but will now require multiple requests.

Who is affected

This change introduces a breaking change for any client that fetches projects, users, or tags across multiple workspaces using the GET /projects, GET /users, and GET /tags endpoints. This issue arises when you call the API on behalf of a user who belongs to multiple workspaces without specifying a workspace or team.

After this update, any such requests will fail unless a workspace or team is explicitly provided.

Change details

  • After the opt-out period (see Timeline below), if an API call is made to GET /projects, GET /users, or GET /tags without a workspace or team parameter and the authorizing user is in multiple workspaces, the request will fail with an error message.
  • If the user is in a single workspace, that workspace will be inferred and used to fulfill the request. Note: if the user later joins an additional workspace, the same request will fail.

Migration steps

To prepare for this change:

  1. Use GET /workspaces to retrieve workspace GIDs for the authorized user

  2. Either:

  • Prompt user to select their desired workspace, or
  • Make separate API calls for each workspace GID to fetch all data
  1. Include the workspace/team parameter in your requests

Timeline

Timeline (approx.) Behavior
Now - June 2025 Opt-In: The workspace and team parameters are not required. Users can opt in to the new behavior (where requests without a workspace or team will fail if the user is in multiple workspaces) using the cross_workspace_deprecation feature name for Asana-Enable
June 2025 - September 2025 Opt-Out: The workspace and team parameters become required when a user is in multiple workspaces. Users can opt out and keep the old behavior (where workspace and team are not required).
After September 2025 The option to opt-out will no longer be available.

Why we’re making this change

We expect these benefits as a result of this change:

  • Better alignment with typical client usage patterns (most clients only need data from a single workspace)
  • Improved API performance for most API clients
  • Consistency with existing Asana API patterns

Questions and feedback

Please feel free to leave any questions or feedback directly in this thread.

5 Likes
2

Hi @Andrew-asana,

I would consider this a breaking change; it’s not labeled as such but seems like it should be?

I.e.:

1 Like
3

Thanks @Phil_Seeman, that’s definitely the case here. This change could be a breaking change for apps that fetch data across multiple workspaces without specifying a workspace or team. I’ve updated the above post to include a brief warning about this change in behavior.

2 Likes
4

I’m glad you clarified that it’s a breaking change because I felt it was and mentioned that to @Phil_Seeman.

But on another note, I feel it could help readers to clarify some wording in your last post and the OP:

Affected apps should not be described as: “…apps that fetch data across multiple workspaces without specifying a workspace or team.”

An affected app need not be attempting to fetch data across multiple workspaces. To run into the problem, they need only be attempting to fetch data in one workspace; if the user happens to be a member of two or more workspaces, then they’ll encounter the problem on just a single call, as I understand it.

Thanks,

Larry

1 Like
5

@Andrew-asana, @Phil_Seeman,

For Asana2Go, I opted-in for the header cross_workspace_deprecation and confirmed that it’s part of my calls in Asana-enable, yet old-style calls like https://app.asana.com/api/1.0/users/me are not failing due to missing workspace parameter as I expected they would be for a Phoenix user who is a member of a handful of workspaces.

Shouldn’t these calls be failing under those circumstances? Am I doing something wrong? Or is this not rolled out yet? According to the OP, it should be rolled out since February.

By “in multiple workspaces” I’m assuming that just means a user would look like this:

image
image630Ă—306 28.5 KB

Or does it require something more, like the user to be active currently in multiple workspaces?

Thanks,

Larry

6

@lpb the endpoint you mentioned https://app.asana.com/api/1.0/users/me is the Get a user (/users/{user_gid}) endpoint. I think you might be confusing it with the Get multiple users (GET /users). This change post does not mention that Get a user (/users/{user_gid}) endpoint is affected.

If you provide the Asana-Enable header with cross_workspace_deprecation for Get multiple users (GET /users) endpoint it should throw and error saying This request accesses data in multiple workspaces. Please specify a workspace or team.

7

Thanks, @John_Vu; users (I mean user!) error.

I had jumped to the mistaken conclusion that any endpoint starting with /users was affected. Thanks for straightening me out.

Much appreciated,

Larry

1 Like
8

Hi all,

Just wanted to confirm that this API change has recently become opt-out rather than opt-in (per the timelines above).

Best,

Andrew

1 Like