OAuth? Personal Access Token? API Key? How to get connected to Asana through our API

platform
api
authentication

#1

A common question we hear about authenticating with Asana’s API is that it’s not particularly clear which method to use to get access to our API. Let’s chat about that!

First things first: if you’re using an API key (our older method of authenticating) to connect to our API

don’t. We’re shutting them off. :wink: Personal Access Tokens (described below) are pretty much the direct replacement for API keys.

Now that we have that out of the way, what’s the difference between an OAuth App and a Personal Access Token (or PAT)?

When first getting started with our API, it’s best to use a Personal Access Token. It’s significantly simpler to get going - you simply create the access token and use it to make requests with our client libraries or curl and off you go. PATs imply that you want the script to act “as you” and you will be the user that shows up in Asana as having taken any particular action.

Edit: we designed PATs to be backwards-compatible with API keys, so integrations built to use API keys can be given a PAT and this should work, though we definitely recommend moving to OAuth apps for multi-user integrations! PATs are better for users, too - if you create a new one for each integration, you can revoke one without losing access to all other integrations. Thanks to @briankb for prompting this note!

OAuth Apps are designed to be used “on behalf of” another user - they are you building a tool, and the tool is used by someone else. This means that the authentication method is much more complicated - you have to potentially involve the user granting access to your application of their Asana data.

However, you want that if you’re looking to build something for other users; the authentication method is designed to keep the user’s (and your integration’s) credentials secret. It’s better for users, too: if you hand out your PAT to multiple integrations, and later decide to revoke access to one, you’re stuck: you have to revoke it for all of them. OAuth apps are designed to work on a per-application basis.

Hopefully this helps you hit the ground running!


#2

Atlassian via JIRA still tries to use your API Key. This is their problem but I thought I would mention it in case you have a relationship and can get them to update their Importer to support the Personal Access Token or OAuth like they already do for their Github importer.


#3

Thanks @briankb! We will definitely follow up! (They’re using our older branding too, hmm…)

If anyone happens to land here from search or some other context, we built PATs to be backwards compatible with API keys in those integrations which have not made the change - you can issue a new PAT and use that in the field for an API key and it should work.


#4

Hi, I’m developing a google plugin that integrate Asana to Google Form using Google Apps Script, We are currently using Personal Access Token (PAT) to make a request to Asana but planning to change it and implement the Oauth since it is more easier for the user. I’m researching for more than a week on how to implement Oauth with Asana but no luck, there’s no detailed documentation on how to do it.

can anyone help me? really need to implement Oauth. You’re help is very much appreciated.

Thanks!!


#5

Thanks for reaching out. We have a section on authentication, including OAuth, in our documentation.

We also have OAuth examples in the Asana Client Libraries.

Hopefully those resources are helpful. Let us know if you have specific questions.