[Change] Upcoming changes to project memberships

English Forum Developers & API Changelog
, , , ,
1

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

Once we release new membership endpoints, 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

March 2024

  • Project support for POST, PUT, DELETE /memberships endpoints (viewer access level may not yet be generally available)
  • Deprecation period begins

Mid 2024

  • viewer Access Level for projects is rolling out and supported through /memberships endpoints
  • Teams as project members

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

John Baldo
Asana API Team

2 Likes
2

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.

3

Hey @Phil_Seeman :wave: ,

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

4

Thanks!

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

Thanks,

Larry

5

Oops. Yes, that’s right. Updated.

Thanks!

1 Like
6

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).

7

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

8

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

2 Likes
9

Excellent news, @John_Baldo - thanks!

1 Like
10

When will the existing endpoints be deprecated?

Thanks!

11

The post was written in July of 2023. By “Later in the year” do you mean later in the year 2024?

12

Hi @Admin_Tester ,

Sorry, the timeline for adding additional endpoints has slipped into 2024 and I don’t have an update. I’ll work on getting that and update here.

2 Likes
13

Updated to reflect:

  • Targeting to have new membership endpoints released by March 2024 (with editor role support, but not yet viewer and teams as members)
  • Will plan to start a deprecation for the previous project membership endpoints at that time

@Admin_Tester

3 Likes
14

@John_Baldo Given that we need to migrate existing production code that uses the existing project membership endpoints and we would need at least a few months to complete that work.

  1. How long will the gap be between the release of new membership endpoints and deprecation of existing endpoints.
  2. Can you provide a date or schedule for deprecation?

Thanks!

15

@Admin_Tester , the same functionality is available now on the new endpoints (reading project membership information). We are just adding additional functionality (the ability to create or modify memberships).

We have the timeline estimates I posted for the next release. We typically do at least 3 months of the ability to opt-in to the change, followed by 3 months to opt-out. We may make that timeline more generous depending on the usage.

1 Like
16

Hello!

I’m writing to let you know that you can now create, update, and delete project memberships over the API! We now support this capability for both goals and projects!

See the API reference here: https://developers.asana.com/reference/createmembership

Later this year, we plan to release the viewer role type. We may close this thread and make future announcements in the API Changelog. Subscribe there for updates!

Thanks,
John

2 Likes
17
  1. How would a customer opt in?
  2. If a customer opted in, would the old projects endpoints be deprecated for them?
  3. How would a customer opt out?
  4. If a customer opted out, would the old projects endpoints continue to work?
18

Customers don’t opt-in our out, but as an API called (per request) you can set a header. We haven’t started this deprecation yet. Deprecations

The simplest way to prepare in this case is to stop using the old endpoints.

19

Hi John.
Regarding to latest message in Asana about access in projects and how admi must decide which access we want people to have in cases when they have two conflicting access.

What happens when we look through the members and no one has two different access? and if the purple bar appears. Also, asana don’t let us decide which access to give and/or update it only let choose one option. Image attached.
Thank you for your support. Hope that i made myself clear.
Asana project access permissions.pdf (147.9 KB)

Screenshot2024_03_06_130930
Screenshot2024_03_06_1309301806×142 68.8 KB

20

Thank you John. The timeline shows the deprecation period starts in March. Has the deprecation period started yet? Can you give us a date when the " Add users to a project" and “Remove users from project” endpoints will be deprecated?