[New] Access levels on portfolios

English Forum Developers & API Changelog
1

Summary

  • We’re introducing editor and viewer access levels for portfolios in the Asana web app and API.
  • Previously, all portfolio members had admin-level access, and access levels couldn’t be modified via the API.
  • Now, you’ll be able to set a default access level for public portfolios and manage user access levels via the API.
  • These additional access levels provide more granular control over what an individual can do within a portfolio.

Behavior changes

  • All public portfolios will have their default access level change to Editor with this rollout. Private portfolios do not have default access levels.
    • If you manage a public portfolio but aren’t a member, add yourself before this rollout to retain your current access (e.g., renaming the portfolio, deleting a portfolio, and modifying privacy settings).
    • After the rollout, you can also reset a portfolio’s default_access_level to admin via the API.
  • Newly created portfolios will also have a default_access_level of editor if a default_access_level is not explicitly set.
  • If you have Editor access to a portfolio, you will only be able to add another member with Editor access or below.
    • This will also apply to the existing POST /portfolios/{portfolio_gid}/addMembers

Detailed look at portfolio access levels
Detailed look at portfolio access levels1702×1286 351 KB

Usage

/portfolios

When creating (POST) or updating (PUT), you may now specify default_access_level which can be one of:

  • admin
  • editor
  • viewer

Example:

POST /portfolios

{
  "data": {
    "name": "My portfolio",
    "color": "dark-green",
    "default_access_level": "editor",
    "public": true,
    "workspace": "167589"
  }
}

/memberships

When creating a new portfolio membership (POST) or updating an existing one (PUT), you will be able to use the /memberships endpoint (in place of the existing and now deprecated /portfolio_memberships) and specify an access_level which can be one of:

  • admin
  • editor
  • viewer

Example:

POST /memberships

{
  "data": {
    "access_level": "editor",
    "member": "12345",
    "parent": "987654"
  }
}

Migration

These API endpoints will continue to work but consider these updates to get the full benefits of new portfolio access levels.

POST /portfolios
  • Consider: Explicitly set default_access_level to admin to maintain current behavior. If this field is not set, the default will change to editor.
POST /portfolios/{portfolio_gid}/addMembers
  • Consider: Migrate to the new POST /memberships endpoint where you can explicitly set an access_level.
GET /portfolio_memberships
GET /portfolio_memberships/{portfolio_membership_id}
  • Consider: Migrate to GET /memberships endpoints where you can fetch more detailed information about a user’s access level.

Timeline

We expect to begin a limited early access period in September and a broader gradual rollout during the month of October. We will update here with more information once we have it (including any major timeline shifts).

Thanks for taking the time to review this information! Please let us know if you have questions or concerns, and we’ll do our best to address them.

John

3 Likes
2

@John_Baldo - re: this,

Can you clarify a couple questions on this:

  1. Upon initial conversion, will existing memberships of private portfolios default to admin?
  2. Does this mean that if I make a POST call to create a membership and don’t pass in access_level, it will work for a public portfolio (based on the default_access_level) but throw an error for private portfolios?
3

Yes, all existing memberships will automatically be converted to admin.

Creating a membership without specifying an access level will make the member an admin, regardless of the privacy setting.

3 Likes