FAQ - Asana's Upcoming Authorization Changes

What is changing for me?
What is a workspace?
What will Asana users see when they authorize an app?
Why are we making this change?
How will it affect my app?
How will I know if I should ask the user for an additional authorization?
How can I get multiple authorizations?
What about Personal access Tokens & Service Account Tokens?
What is the timeline?
What do I need to do to get ready?
Where can I get updates or ask questions?

What is changing for me?

Right now, when a user authorizes an app, they authorize that app across all of their workspaces. Similarly, when an Admin in an Enterprise workspace blocks an app, they block that app for users across all of their workspaces.

Later this year, we will be introducing a workspace picker on app authorization so that users can selectively choose which workspaces they wish to authorize for a particular app. And when Admins block apps, they will only block the app for the workspace they administer.

The majority of our users only belong in a single workspace and, for them, there will be no behavior change. For users who belong to multiple Asana workspaces, there will be an additional step when authorizing apps that asks them to select a workspace.

For app developers, the initial user authorization will be scoped to a single workspace. To your app, it will appear as if that user only belongs in a single workspace (& to reiterate, the majority of users only belong to a single workspace so your app should already support this state). It is possible for that user to authorize the app in multiple domains, but to do so, they must go through authorization again.

Any existing authorizations and access tokens will continue working as expected.

What is a workspace?

Workspace is the top level container for all teams, projects, portfolios in Asana. A user can belong to multiple workspaces. For example a guest, or contractor working at two different companies. Another example might be to have a test Asana workspace (sandbox) and a live, production Asana workspace.

We use workspaces as a generic term here to mean workspaces & organizations. Workspaces can have accounts with generic email addresses like @gmail.com whereas organizations cannot.

What will Asana users see when they authorize an app?

Users who belong in a single workspace will not experience any change. Users who belong in multiple workspaces will now see a workspace picker when they authorize an app.

Users in multiple workspaces will be prompted to choose a workspace. The exact design is subject to change.

Why are we making this change?

Based on customer feedback, we believe this model more closely aligns with industry best practices, security standards, and experience. Our motivation is to put more controls in the hands of our customers so they can be intentional about where they wish to authorize an app.

With this change, it will now be possible for an Admin of an Enterprise workspace to block an app in the workspace they manage, but not block the app for that user across all of their workspaces. For example, let’s say I am contracting for a customer and I am added as a guest to their workspace. If that workspace’s Admin has blocked Google Drive, in today’s world, I am now blocked from using Google Drive in all of my workspaces. When we make this change, I would only be blocked from using Google Drive in the workspace where it was blocked.

How will this affect my app?

1. Existing authorizations will continue working as expected.

The existing token will work for users and all their previously authorized workspaces. However if that user gets added to another workspace, additional authorization will be required for your app to work on the new workspace.

Users with multiple workspaces authorized will be able to choose to de-authorize the app in only a single workspace.

2. New authorizations will be scoped to a single workspace by default, but more workspaces can be authorized by the user.

This is the heart of the change we are making. New app authorizations will have the workspace picker in the OAuth flow and those authorizations will be scoped to a single workspace.

The majority of our users and of all users who use apps only belong in a single workspace, so for that user and for your app, this should be the exact same experience.

For users who belong in multiple workspaces, they will choose to authorize your app in a single workspace. To your app, it will appear as if that user only belongs in a single workspace. However, it is possible for the user to authorize the app in more workspaces if desired.

3. If you wish to ask for more authorizations than initially given (multiple workspace authorizations), the user needs to be sent back through the OAuth flow.

While we can’t be sure of all the ways in which specific apps will be affected by this product change, we foresee a few scenarios in which multiple workspace authorization could be desired. In the section below, we outline those scenarios along with our recommendations for getting multiple workspace authorizations once this change is introduced.

How will I know if I should ask the user for an additional authorization?

We don’t know all the scenarios where this might apply, but here are a few examples we think could require additional authorization:

Scenario: User authorized the wrong workspace by accident

If a user accidentally picks the wrong workspace, they may want to be able to authorize another workspace. Our recommendation is that the user revoke the authorization and attempt to authorize the app again. We will document this in our user focused how-to documentation.

Scenario: Your app has an existing workspace picker and now all the workspaces for that user aren’t showing up as they did before

We know that some of your apps already have their own workspace pickers. We have seen app experiences where a user is asked to select one of their workspaces in your app and then perform other actions like select a project in order to create a task.

When the new authorization is launched, newly authorized users will only see the workspace they have selected in that menu. Arguably, this is the only workspace that the user wants to see in that menu because it’s the one they intend to use for your app. However we know that some users may wish to use your app on multiple workspaces.

In this case we recommend adding an option in your app for the user to “Add another workspace”. This is the most direct way to get them to authorize another workspace.

Example from Asana Partner, Zapier

Scenario: Your app makes cross-workspace requests

It’s possible that your app intentionally makes requests across workspaces. For example, you may use the API to query across all workspaces a user belongs to generate a list of “My tasks”.

In this case, you can display the workspaces your app is authorized for and prompt the user to “Add another workspace”. This would send them back to the authorization endpoint where they can authorize your app to access an additional workspace.

Do you have another critical scenario we haven't thought of? Feel free to let us know.

How can I get multiple authorizations for a user?

If you wish for users to authorize their app in multiple workspaces, here is what we recommend:

• In your app experience, ask users to “Add a new workspace” and direct users to the OAuth consent screen. If any domains are unauthorized we will show the picker.
• If a user is attempting to use your app from a workspace where they have not yet authorized, we would produce a 403 Error. Based on this error, we recommend that your app direct that user to the OAuth authorization screen.

What about Personal Access Tokens & Service Account Tokens?

Service Account Tokens (enterprise only) are scoped to a workspace by default. There is no change for this type of token.

All Personal Access Tokens created before this change can be used in multiple workspaces. All Personal Access Tokens created after this change will be permanently scoped to a single workspace of your choosing upon creation. Developers will see a workspace picker in the Developer Console.

What is the timeline?

These changes will roll out in mid-late summer 2023. We will post an exact date in the coming weeks.

We will be following up to communicate about how you can sign up to test and what to expect for the roll out of this change.

What do I need to do to get ready?

Right now you can start to investigate what about your app may need to change to support this authorization change. For example, does your app rely on multiple authorizations? Does your app have a workspace picker?

If so, it's possible you will want to change the behavior of your app to request multiple authorizations when we roll out this change. We recommend reserving some time on your roadmaps to update and test your apps for summer 2023.

We will follow up soon with much more detail on how to test apps and when you can start testing.

Where can I get updates or ask questions?

We will be sending updates to the email associated with your app. We will also be updating this forum post. And we will continue to update this FAQ.

If you are feeling concerned, confused, please ask us a question in this form.

We know change can be hard. We are so excited about this change to our platform and we want to support our developer community through it. As always, thanks for building with Asana!