[Change] Upcoming changes to project memberships

[John_Baldo]

Hello!

We’re making changes to simplify and standardize the way privacy and permissions are managed in Asana, starting with projects! This post outlines the Asana API changes coming over the next 6-9 months to support this new functionality.

Who is Impacted

You might be impacted or interested in these updates if your application reads or updates a user’s access to an Asana project.

For example:

• Adding or removing users from a project
• Checking to see what access level a user has to a project

What’s new

Access Levels for projects

Asana is introducing Access Levels for project permissions. Today, each project member has a write_access. Going forward, members will have an Access Level expressed as an access_level over the API. Here are the access levels and their definitions:

Going forward: access_level	Previously: write_access	Access
admin	full_write	Can change the project’s content and structure
editor	no equivalent	Can change the project’s content, but not its structure
commenter	comment_only	Can comment on the project’s content
viewer	no equivalent	Can only view the project’s content

The Individual user project permissions section of this guide has more complete definitions of the editor role which is now available. The viewer role will be available later this year.

Default Access Level for Projects

Previously, admin (write_access: full_write) was the default permission when adding a new member to a project. The new default permission will be the editor Access Level. If you add a member using the POST /projects/{project_gid}/addMembers endpoint, they will be given the editor access level.

Right now, there is not a way to modify this project permission level over the API, but this support will be added by the beginning of 2024.

Teams as members

Today, only users can be members of a project. Later in the year, we will support the ability for multiple teams to be members of a project. Teams can be given the same Access Levels as defined above. Each member of that team will be given access to the project and inherit that access level. As members join or leave a team, they will gain or lose access accordingly.

These permissions will be additive meaning that if individual and team membership access levels conflict, the higher access level is granted.

API interface changes

New /memberships interface

Once all of these changes are rolled out, Asana’s /memberships endpoints will be the preferred way to access and modify project memberships.

[
  {
    "gid": "69434",
    "resource_type": "membership",
    "resource_subtype": "project_membership",
    "member": {
      "gid": "93638",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "parent": {
      "gid": "12345",
      "resource_type": "project",
      "name": "Upcoming Product Launches",
      "owner": {
        "gid": "37204",
        "resource_type": "user",
        "name": "Rainbow Randolph"
      }
    },
    "access_level": "admin"
  },
  {
    "gid": "13713",
    "resource_type": "membership",
    "resource_subtype": "project_membership",
    "member": {
      "gid": "56789",
      "resource_type": "team",
      "name": "Marketing Team"
    },
    "parent": {
      "gid": "12345",
      "resource_type": "project",
      "name": "Upcoming Product Launches",
      "owner": {
        "gid": "37204",
        "resource_type": "user",
        "name": "Rainbow Randolph"
      }
    },
    "access_level": "commenter"
  }
]

Deprecating project_memberships endpoints

Later in the year, we will begin a deprecation cycle for existing project_memberships endpoints and endpoint and project endpoints which add or remove members.

Existing endpoint	New endpoint
GET /projects/{project_gid}/project_memberships	GET /memberships
GET /project_memberships/{project_gid}	GET /memberships/{gid}
POST /projects/{project_gid}/addMembers	POST /memberships
POST /projects/{project_gid}/removeMembers	DELETE /memberships

Reason for change

We want to give customers more data access control in Asana. Access Levels will simplify Asana’s permissions model and make it easier to understand who has access to a given project. Over time, other objects in Asana like portfolios and goals will transition to Access Levels.

Teams as members will further simplify access control and make it easier to manage access. When combined with Asana’s identity provider integrations, many access control decisions can be automated over the lifecycle of a user. For example, as an employee joins a team or moves between teams, their Asana access will update to reflect the change.

Timeline

Here is a rough timeline we are targeting for these changes. We will post updates in this thread. You can subscribe to this thread for updates.

Available now / July 2023

• editor Access Level for projects
• editor is the default Access Level for a project
• GET /memberships endpoint for projects (with editor Access Level support) - by the end of the month

Late 2023

• viewer Access Level for projects

Beginning 2024

• Teams as project members for projects
• Project support for all Access Levels via POST, PUT, DELETE /memberships endpoints

Thanks! Let us know if you have questions or thoughts for us!

John Baldo
Asana API Team

[Phil_Seeman]

Hi @John_Baldo,

This is great to know that we’ll have full API access to read/modify memberships by early next year.

A few questions/comments, for now:

1. The previous plan to update memberships incuded a new effective-access_level property. Is this still happening or is that element gone from the new design?

2. I just wanted to point out a hole in the previous plan, which was raised here - the ability to get all team memberships for a user - and make sure that was on the API team’s radar to make sure it won’t get lost in the upcoming design.

[John_Baldo]

Hey @Phil_Seeman ,

Thanks for the reply!

Ah, I didn’t realize effective-access_level was part of the conversation in the past. I think right now we’re stepping back to think holistically about the question: “how can we make it convenient to check the effective access level of an individual on an object?” given these upcoming changes (especially teams as members). We’re still considering whether or not that past proposal is the right answer.

If you have examples of instances where your application could benefit from an “effective access check”, we’d be very interested in hearing about them!

Thanks for flagging the consideration about team memberships. At the moment, we’re working on projects, but as Sasha’s post noted - we expect other Asana objects to support this scheme over time, so we’ll consider that!

Thanks again,
John

[lpb]

Thanks!

@John_Baldo

Previously: write_level

I’m pretty sure this and one other occurrence should be write_access, correct?

Thanks,

Larry

[John_Baldo]

Oops. Yes, that’s right. Updated.

Thanks!

[FreshyJon]

@John_Baldo

• editor is the default Access Level for a project

I also wanted to raise the same point that I made here: Introducing new access level in projects - “Editor” - #3 by FreshyJon (as well as others who commented similar issues).

The new Editor role may be considered “Default” now, but that should arguably be an option/setting as the organization level.

As well, it seems that it’s not just the new Default, but also retroactively changed existing projects too (which puts undue burden on us now). As mentioned by @anon66901816, you’ve changed “existing functionality”.

I strongly recommend that existing projects prior to this change be allowed to maintain the admin access level. In addition, such a feature shouldn’t roll out, unless Project Template are also able to leverage it (which doesn’t seem to be the case as of now).

[John_Baldo]

Hi @FreshyJon ,

Thanks for noting that. I’ve passed on the feedback to our permissions group and will work on clarifying the impact to existing projects in the language here.

We’re reviewing the feedback and monitoring the API activity to think through what we can provide to make things more flexible.

Thanks again,
John

[John_Baldo]

Hi @Phil_Seeman, @FreshyJon and others who might be interested. A couple updates related to this…

1. The GET /memberships endpoint should now return project memberships with the new editor access level.

2. In response to feedback about the default access level change, our permissions team released the ability to set a new field called default_access_level when creating or modifying a project over the API. Currently, the value can be one of: admin, editor, commenter . When a user is added to a project, they should be given that access level by default. Eventually, viewer will also be added as an option.

We are working on adding this information to the documentation, but you should see it mentioned in some places.

John

[Phil_Seeman]

Excellent news, @John_Baldo - thanks!

[Admin_Tester]

@John_Baldo

Later in the year, we will begin a deprecation cycle for existing project_memberships endpoints and endpoint and project endpoints which add or remove members.

When will the existing endpoints be deprecated?

Thanks!