Building the app

Authenticating your app

Asana’s API has several options for authenticating. The purpose of your app, who uses it, and its features will dictate the method of auth that’s best for your app. For an overview of the various authentication options and why you might want to use each of them, visit the documentation for authentication.

---

Reacting to changes

It is common for apps to need to determine what has changed in Asana. Knowing this enables many different features and types of apps, such as: reporting, data-backup, keeping two data sets in harmony, triggering automations, and syncing apps, to name a few.

Events are a special type of object that indicate something changed on a specific resource object in Asana. There are two primary mechanisms to programmatically determine what’s changed:

1. Poll for events, or
2. Receive events via webhooks

There are advantages and trade-offs for each approach. Generally, it is advisable to use polling unless your app’s features require reacting in real time to events Here is an overview of each option:

When to use polling

• When you don’t need real-time updates. Common examples:
  • Reporting apps
  • Data backup
  • Syncing integrations or automations that don’t need to react in real time

When to use webhooks

• You need real-time communication
• You want to respond immediately to an event
• You want to push data immediately based on changes

🚧

Use polling instead of webhooks if possible

Avoid using webhooks unless reacting to events in real time is a strict requirement for your app.

Challenges with webhooks

Webhooks based solutions are more technically challenging to implement than polling. Here are some of the common challenges and considerations when working with webhooks:

• Webhooks require creating and maintaining a server to receive events
• Webhooks require complex and thoughtful architecture e.g. to avoid infinite loops when implementing 2-way syncs, mitigating the fallout from bugs, etc.
• Webhooks are unreliable and will need a backup solution. Eventually, both your server receiving webhooks and Asana’s service sending them will experience some downtime. This will likely require a back-up polling solution to get systems back in sync.
• Webhooks are ephemeral and easy to mishandle or lose
• Asana webhooks are noisy and can be challenging to reason about – a single user action in Asana can result in many events being sent to your server

If your custom app requires real-time reaction to event data, visit these resources implementing Asana webhooks:

• Webhooks developer guide
• Webhooks API reference documentation

---

Using bots

If your app needs to take action in Asana (e.g. interact with tasks/projects/comments etc.), you may want to authenticate these actions with a bot account so Asana users see your app’s actions authored by a machine and not a human colleague.

Creating a bot

1. Create an email account with your organization’s email domain (you can use an existing one if it’s not already in your Asana org)
2. Create a new Asana user in your org using this email account. You can do this through the API, UI, or have your Asana admin do it
3. Login to Asana as this new user
4. Update the Asana account profile to make it clear that this is a bot account with a specific purpose and not a human
5. Go to the developer console and generate a PAT
6. Use this PAT to authenticate your app

Restricting scopes

If you want to change your app’s permissions, follow the above instructions for creating a bot except create an Asana account that is a limited access member or guest instead of a regular member of the org. These account types have limited access within Aasna and can only see the projects/tasks they’ve been invited to.

Guests are more restricted than limited access members. Read the linked docs to understand the nuances between these account types and how they’re restricted. These restrictions will be mirrored in the API.

Note: Limited access members need to have the same email domain as the rest of your Asana organization. Guests need to have a different email domain.

To restrict scopes, log back into your normal Asana account. Then, invite the new limited access or guest user you just created only to the tasks/projects that you want it to have access to. Your app’s scope will now be limited to the permissions of the guest/limited access account you’ve created.

📘

More features coming soon

Asana is actively building more API scopes and better bot features. To stay informed on new platform features such as these, subscribe to the news section of the developer forum.