[ New ] OAuth permission scopes

English Forum Developers & API Changelog
1

Summary

We’re introducing a redesigned OAuth consent experience for new apps that supports OAuth (permission) scopes. This change allows developers to request the least privileged access necessary for their integrations, increasing both user trust and application security.

Previously, apps requested full access to a user’s Asana account. With this update, developers can now specify the exact objects and actions their app requires—e.g., tasks:read, projects:write, users:read. We expect apps using scopes to get greater adoption amongst users, particularly Enterprise customers.

Who is affected

This preview release includes 14 granular scopes that can be registered for new apps. Existing apps will continue using full permissions until these self-serve granular scopes are made available later. If you’re building a new integration and registering granular scopes, you’ll automatically see the new scope-based consent screen.

For developers using the preview, your app will request a specific list of scopes at auth time. If you need to change the permissions granted, the user must re-authorize the app.

Timeline

  • Developer preview: Available now for new apps
  • More scopes & usability improvements: Ongoing updates through June 2025
  • General availability: Expected July 2025

By GA, we will be implementing:

  • [SOON] Scopes are presented alongside API endpoint documentation
  • Self-serve scopes registration for existing apps
  • Developer usability improvements like a token introspection endpoint to assert scopes available to a given token
  • More granular scopes!

Usage

As you register your new application in the OAuth tab of your developer console, you can specify which OAuth scopes your app can request:

scopes1
scopes1934×1116 88.4 KB

In the example above, the following OAuth scopes were selected: projects:read, tasks:read, tasks:write, and tasks:delete.

Keep in mind that only pre-approved scopes will be accepted during user authorization. You must explicitly specify the desired scopes using the scope query parameter when requesting user authorization. For example:

<a
  href="https://app.asana.com/-/oauth_authorize
?client_id=753482910
&redirect_uri=https://my.app.com
&response_type=code
&state=thisIsARandomString
&code_challenge_method=S256
&code_challenge=671608a33392cee13585063953a86d396dffd15222d83ef958f43a2804ac7fb2
&scope="projects:read users:read workspaces:read attachments:write tasks:write"
>
  Authenticate with Asana
</a>

Scopes are space-separated (URL-encoded). Tokens issued will only have access to the scopes listed at authorization time.

Upon visiting the authorization endpoint with the above link, the user will be greeted with a screen that looks like:

image (1)
image (1)1246×1041 96.9 KB

See the full OAuth scopes documentation for a comprehensive guide to get started!

Migration steps

If you’re currently using “full access” and would like to preview OAuth scopes:

  1. Register a new app in the developer console.
  2. Specify only the scopes your app needs.
  3. Update your auth flow to pass those scopes via the scope query parameter.
  4. Test API requests in Postman or your app.
  5. Handle 403 errors by checking for missing scopes and updating your scope list.

For example, a request like


GET /tasks/123?opt_fields=assignee.email

Will fail with a 403 unless you include the users:read scope.

Why we’re making this change

OAuth scopes are part of our ongoing effort to increase developer control, strengthen security, and build user trust. Implementing OAuth scopes in your applications offers several key advantages for developers:

  • Granular access control: Scopes allow you to request only the specific permissions your app needs, reducing the potential attack surface and minimizing security risks.
  • Improved user trust: By requesting minimal permissions, you create a more transparent OAuth flow, increasing user confidence in your application.
  • Easier compliance: Scopes help you adhere to the principle of least privilege, making it easier to comply with data protection regulations and security best practices.
  • Streamlined enterprise approval: Apps with well-defined, minimal scopes are easier for enterprise administrators to review and approve, potentially increasing your app’s adoption in corporate environments.

Resources

Questions and feedback

We’d love to hear how you’re using OAuth permission scopes and what additional permissions you’d like to see.

Let us know:

  • Along with the full scopes list above, which other scopes are you excited for?
  • Is the preview working as expected for your new app?
  • Existing app and want to use scopes? We’d be happy to partner with you to get your app migrated to use scopes prior to GA!
  • What tooling support, if any, would improve your experience?
5 Likes
3

Hey @Andrew-asana , I was not able to use the stories:read scope, it was enabled in the new asana app as well included in the authorization. The other read scopes though work as expected

4

Hey @karthikeya_satti,

I am not able to reproduce this issue with the two stories:read endpoints:

  • GET /stories/{story_gid}
  • GET /tasks/{task_gid}/stories

mentioned in OAuth scopes

Are you getting an error back? I am assuming you selected the “Read” checkbox under “Stories” form your app’s oauth page under “Permission scopes”