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. Personal Access Tokens (described below) are pretty much the direct replacement for API keys.
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!