What is an Asana app?

An Asana app makes it possible to extend or enhance what’s possible with Asana. Many people build Asana apps to integrate with other tools, add or extract data about the Work Graph, or automate workflows.

Apps can be built and then shared with other Asana users or they can be built just for your organization. Apps can be built for individual users, for example Google Drive which attaches Google files to tasks. Apps can also be built to run org-level processes. For example like onboarding users from Okta or running custom scripts.

Build an app and publish to the App Directory

If you are building an integration with a 3rd party tool and intend for any Asana user to discover it, apps can be published to the Asana App Directory. The app directory is a great place for users to discover new apps that help them get the most out of Asana. We recommend visiting the app directory and try using an app to learn more about what’s possible to build with Asana.

Build an app for just one organization

If your app is not meant to be used by any Asana user, apps can also be created and then shared with only organizations of your choice. By default, all apps start out private to the developer. You can change the sharing permissions of your app in the Manage distribution tab inside the developer console.

Asana apps use features like our rest API, app components, and webhooks. Learn more about how these features are used to power our most common use cases.

What do I need to know before I build an app with Asana?

While no two apps are exactly the same. We have a general set of best practices that will help you build a successful app with Asana.

Here’s an overview of the steps you will need to follow to build an app.

Plan your app

Before you get started building your Asana app, we recommend you familiarize yourself with the Work Graph, meaning the core Asana objects and their relationships. Check out this quick guide on understanding objects.

Next, we recommend planning your app. This step helps you define the exact problem your app is meant to solve and become familiar with features in the Asana platform that will help you build the right solution. Check out our library of use cases, example apps, and other apps in the directory for inspiration.

Get started with the API

The next step is to try using the API to test how it works. The primary feature of Asana’s platform is our rest API, so we recommend getting familiar with how our API works.

Here’s a brief overview of how to get started:

1. Choose your test workspace. You can test in any of your existing workspaces, create a free account, or request a developer sandbox. The developer sandbox will allow you to test premium features not included in a free account.
2. Choose your authentication method. Your app may ultimately use OAuth, but most developers test our API by creating a Personal Access Token (PAT) to make their first API calls.
3. Create your token or app in the developer console.
4. Use your token to make an API call. Visit the API Reference and learn about the different types of APIs that are available. Our embedded API explorer lets you try using the API from the reference. Build your request on the documentation page, press “Try it” and see a response in seconds. If you’d like a step by step guide for making your first API call, check out our quick start guide.

Build and share your app with its intended audience

Once you have your app planned, and have moved beyond testing the API, you’re ready to build your app. If you are building with a PAT or Service Account token, your app can only be used in your organization. If you are building an app for any user to discover, we recommend creating an app and using OAuth. All OAuth apps are created privately by default. You will need to change the app distribution setting to either share the app with just a specific organization or to anyone with the OAuth redirect URL.

1. Learn more about the different features you might want to consider like webhooks for reacting to changes in Asana or app components for embedding apps directly into Asana.
2. Use the API reference to determine what types of API calls will best serve your use case.
3. Set-up your authentication method (OAuth recommended). Learn more about authentication options.
4. Write your app code. If you would like to start from an example, you can check out our Github repository of example apps.
5. Deploy your app.
   1. Locally - For a simple script, creating a launchd job (or Windows task scheduler) may be sufficient, whereas more complex apps or those using features like webhooks or app components, will have more sophisticated hosting, security, and uptime requirements.
   2. Hosted - Some developers choose to use their company’s on-prem solution, many use hosting providers. If your company doesn’t already have a hosting provider that you can use, here are some common choices:
      Amazon Web Services (AWS), Google Cloud, Heroku, Microsoft Azure, IBM Cloud, SAP, Vercel
6. Share your app (optional). When your app is ready to use, we recommend checking your distribution settings. In the Developer Console > Manage distribution. There you can share your app with more workspaces or choose to share your app with “any workspace”, meaning any user with the OAuth Redirect URL can authorize the app. If you are using a PAT or Service Account token, sharing your app will not be necessary as those tokens can only be used in workspaces where you are a user.
7. Publish your app (optional). If you would like your app to be published in the Asana App Directory. Set your distribution to “any workspace”, then follow the instructions on the Developer Console > Submit for Review page.