Share your app

When you are ready to allow others to use your OAuth app in a workspace, visit the Manage distribution tab for your app in the developer console. There, you can choose to share your app with either (one or more) specific workspaces or with any workspace:

Specific workspaces

Sharing your app with specific workspaces allows you to share the app with any workspace(s) that you are a member of. To begin:

1. Select Specific workspace. Once saved, select + Add workspace:

2. Choose a workspace from the dropdown menu and select Add. This will allow any member of that workspace to authorize the app when given an authorization URL or the user authorization endpoint.

📘

Which workspace(s) am I member of?

Along with seeing your options in the dropdown (as shown above), you can retrieve your workspace memberships via the API by making a request to GET /users/{user_gid}/workspace_memberships.

Alternatively, if you are already logged in to the Asana app in your browser, you can also visit https://app.asana.com/api/1.0/users/me to quickly get your workspace membership records. Under the hood, this is a request to GET /users/{user_gid} for the currently logged in user.

3. You may also select additional workspaces in which to distribute your app:

Any workspace

If your app is intended to be shared with many users, select Any workspace. This will allow users from any Asana workspace to authorize the app if they are given the authorization URL.

📘

App directory distribution

All apps submitted for publication to the app directory must be shared to Any workspace.

Change sharing settings

For unpublished apps (i.e., apps that are not in the app directory), you can change your app distribution settings at any time.

Note that that changing the sharing settings from Any workspace to Specific workspace will block any new authorizations from users outside the specified workspace:

---

Manage app installation

When the end user connects an app with app components to Asana for the first time, they will go through an app installation flow. This involves authorizing the app, then adding it to projects in Asana.

The installation flow can be configured in the developer console. A list of all possible configurations can also be found in the configure the app section of the getting started guide.

Installation entry point

For the end user, the installation flow can be triggered through either one of two ways:

1. The in-product app gallery. Users can access the app gallery by going into a project (in which they want to install an app), then navigating to Customize > + Add App.

📘

App gallery visibility

If you intend for an app with app components to appear in the app gallery of a particular workspace, the app must first be installed. Installation occurs if either:

1. The app gets added to a specific workspace
2. The user authorizes and installs the app with a deep link (this must occur even if any workspace is chosen)

2. Asana's app directory. Users can also access the Asana app directory directly to install an app.

Note that subsequent interactions with the same application by the same user will not trigger the following installation flow. To force the installation flow in its entirety again (e.g., for QA purposes), you can visit https://app.asana.com/-/install_platform_ui_app?app_id=<app_client_id>, replacing the value of the app_id query parameter with the application's client ID (accessible via the developer console).

App details

If the user installs the app via the in-product app gallery (i.e., the first scenario above), the user can see more details about the app:

The information on this page can be customized in the App listing details tab of the developer console:

For more information, see the configure the app section of the getting started guide.

Authentication

On the next screen, the user will be directed to the auth screen, which will ask them to connect to the external app.

When the user clicks the button to continue, Asana will make a request to the application's specified Authentication URL in a pop-up window. From here, it is developer's discretion as to how the user proceeds with authentication. In most cases, this authentication step usually involves completing the Asana OAuth flow, as well as the third-party (i.e., external) OAuth flow.

Additionally, you may choose to present custom screens, forms, or otherwise logic to prompt the user for additional information needed to set up the application.

The authentication flow is concluded when the app confirms that authentication is complete with a "success" message using window.postMessage. For more information, feel free to review authorization requirements when publishing an app.

Add to projects

Once the user has successfully granted permissions, they'll be taken to different screens depending on how they entered the installation flow:

1. If the user began the installation flow from outside of a project (e.g., through the Asana app directory), the user will be shown an additional screen that prompts them to add the app to any necessary projects. This screen will not be shown otherwise.

From here, the user may choose to add the app to one or more projects, or even skip adding the app for the time being. Once the user has made their choice, the final screen will confirm the user's choices, and the installation flow will be completed.

2. If the user began the installation flow from within a project, the user will see a confirmation of the app they've added, and the installation flow will be completed.