[Halted] Upcoming changes that impact getting and setting memberships and access levels


tl;dr:


Hey folks,

We’re making some changes to the way you use memberships API. As part of this
change we’ll be retiring a number of endpoints, and adding new endpoints.

The /memberships endpoint is now available for everyone. The old endpoints
will remain available until the end of the opt-out period.

Old Endpoints New Endpoints
  • GET /memberships
  • PUT /memberships/{gid}
  • POST /memberships
  • DELETE /memberships/{gid}

Key Terms

  • Membership-capable resource: Asana objects that have API resources that
    support user membership:
    • Goals
    • Portfolios
    • Projects
    • Teams
    • Workspaces

Current Behavior

  • Memberships for various entities have specific sets of endpoints and
    resources to represent these memberships
  • Only users can have memberships
  • All members of membership-capable resources have the same access level as
    the membership-capable resource

New Behavior

Users have a standard_access_level for Projects, Portfolio, and Goals via
their direct membership.

However, users may be on a team that has a different standard_access_level
than their direct membership. When there is a difference, the highest access
level across all memberships (if a user is on several teams with access),
becomes the effective_access_level. This effective_access_level is then used
to determine the user’s tier of access.

  • One set of endpoints will be responsible for management all memberships

    • The new Memberships resource will define the Asana resource for
      membership (e.g., Project, Team, Goal, etc)
  • Memberships can now include teams, such that you can add or remove an entire
    team from an Asana resource that supports membership

  • Access-levels for members of membership-capable resources are determined by
    their highest party membership, and this is called effective_access_level.

    • E.g., when a member has access to a membership-capable resource for
      multiple reasons, such as through direct membership or through a team
      that has membership, the highest access level of these associations is
      used to determine their access to the resource.

    • Important: The effective_access_level field of the Memberships
      resource won’t be available until a separate changeset. But, the access
      level will impact requests when this changeset becomes available for
      Opt-In.

  • Prototype of the new Membership resource (when a member can be a team or a
    user):

    {
      "member": {
        "gid: "123",
        "resource_type": "<user or team>",
      },
      "parent": {membership-capable resource},
      "resource_type": "membership",
      "resource_subtype": "<one of team_membership, project_membership, workspace_membership, portfolio_membership, goal_membership>",
      "<subtype-specific fields>": "<subtype-specific values>"
    }
    
  • Prototype of the new Membership resource (when a member can only be a
    user):

    {
      "user": {
        "gid: "123",
        "resource_type": "user",
      },
      "parent": {membership-capable resource},
      "resource_type": "membership",
      "resource_subtype": "<one of team_membership, project_membership, workspace_membership, portfolio_membership, goal_membership>",
      "<subtype-specific fields>": "<subtype-specific values>"
    }
    

Impact

  • If you rely on the ability to add, remove, or query members from any
    resource, you will need to start using the new endpoints by April of 2023

Timeline

Date Event
2022-10-21 Original announcement
2023-01-19 Timeline adjustment
2023-01-25 Spec adjustment[1]
2023-02-06 Opt-In available
2023-02-21 Opt-In announcement update and corrections[2]
2023-03-02 Opt-In announcement pause
2023-03-10 [WILL CHANGE] Opt-Out available
2023-04-19 [WILL CHANGE] Generally Available (opt-out no longer available)

Yours in Developer Relations,
Sasha, on behalf of the Asana API Team


  1. added clarifying text about effective_access_level and removed
    GET /memberships/effective_access_level/parent. ↩︎

  2. made it clearer that member is a resource and not a GID. ↩︎

4 Likes

Thank you for the update. Couple questions about the direction this is going:

Will the new API endpoints support changing owners to a membership-capable resource? Specifically, for Portfolios, there’s currently no way to assign an Owner via the API. Can there be a “role” parameter added to the Membership resource for this purpose?

Reason I’m thinking “Roles” for Portfolios is because it would align well with “Roles” in Project Memberships. In the Overview page of a Project, the “Project Owner” role can be assigned with the projects endpoint but the same cannot be said about the portfolios endpoint. Seems like an additional “role” parameter to the Membership resource would do the trick?

Thanks in advance. Keep those updates coming! :slightly_smiling_face:

Hi folks, this has not yet started rollout. We expect to provide an updated rollout date in January of 2023.

2 Likes

Hi folks,

We have an updated timeline for these changes:

Date Phase
2023-02-06 Opt-In available
2023-03-10 Opt-Out available
2023-04-19 Generally Available (opt-out no longer available)
3 Likes

Hi @sasha_f !

Couple of things:

This should be “add, remove, or query members from any resource”, yeah?

Can you elaborate on what “effective_access_level” means here? Thanks!

:white_check_mark:

Users have a standard_access_level for Projects, Portfolio, and Goals via
their direct membership. At the moment in the API, we’ve exposed this standard_access_level as write_access and other properties – this is part of what will also be changing once we update the docs and schema.

However, users may be on a team that has a different standard_access_level
than their direct membership. When there is a difference, the highest access
level across all memberships (if a user is on several teams with access),
becomes the effective_access_level. This effective_access_level is then used
to determine the user’s tier of access.

That said, we actually have modified the spec for this feature for the first
iteration to remove the GET /memberships/effective_access_level/* routes. We
expect to add it back the feature as a property on membership objects instead of its own
endpoint to improve the ergonomics for API users.

I’ll update the original post with these details and your first comment!

2 Likes

@Phil_Seeman I need your help navigating the updates: does this mean we can now programatically put someone as comment-only on a project?

1 Like

My instinct here is no, but I’m actually not sure and will find this out for you! It might be mid-next week that I get the answer tho.

1 Like

ok, so it turns out yes, with this change you can set someone as comment-only. Here’s how you’d do it:

{
  "member": "<User or Team resource>",
  "parent": "<membership-capable resource>",
  "resource_type": "membership",
  "resource_subtype": "project_membership",
  "standard_access_level": "commenter",
  "<subtype-specific fields>": "<subtype-specific values>"
}

standard_access_level for project_membership will include the following values:

  • editor
  • contributor
  • commenter
4 Likes

Excellent, thanks so much!

@sasha_f

Does it mean we can’t test it before February 6th, when we’ll have to optin?

The code you shared, can I use it to do a PUT on memberships/XX_GID_XX and simply passing { "standard_access_level": "COMMENTER" }?

Thanks

If the user is already a member of that sources, it would be the PUT form. If the user is not a member, you’d use the POST form and then be issued a membership gid in the response.

And yes, until this becomes available as opt-in, you won’t be able to test it. I will comment on this thread once it becomes available (which we’re anticipating is tomorrow).

2 Likes

Hi @sasha_f,

I have a few questions:

  1. When the resource is a team, can it have a team as a member? (If yes, then can that be the same team as the resource? I would assume no.)

  2. In the first prototype you show where the resource can contain users or teams, how does one know whether a given member is a user or a team?

  3. To make sure I’m clear: standard_access_level will be returned, and can be set, when this changeset is in effect. However, effective_access_level will not initially be available to get or set.

  4. If I’m right on #3, then this would seem to mean that while one will receive a standard_access_level for a member, it might not be the access level that’s actually in effect for that member (if they have a higher effective_access_level that we won’t be able to see). Similarly, one can set standard_access_level, as in your example of setting a comment-only user, but that action might not actually have any effect if the user has an effective_access_level that’s higher than the one that’s being attempted to be set (and after making the call to set the standard_access_level, we’ll have no way of knowing whether it actually worked or not).

1 Like

@sasha_f is this out yet :slight_smile: ? thanks

1 Like

Hey folks, this is now available as Opt-In, and with the /memberships endpoint available for everyone.

No, teams cannot have other teams as members.

The member field will point to a team or user resource, which will have a resource_type field, like so:

{
  "member": {
      "gid": "123",
      "resource_type": "user",
  },
  "parent": "<membership-capable resource>",
  "resource_type": "membership",
  "resource_subtype": "<one of team_membership, project_membership, workspace_membership, portfolio_membership, goal_membership>",
  "<subtype-specific fields>": "<subtype-specific values>"
}

This was confusing in the OP, and I’ll update to include this! Thanks for the keen eye and great question!

Correct, as of now, the following are true:

  • only standard_access_level is available
  • effective_access_level is not available
  • it’s possible that the “effective access level” (which will be available in the future as effective_access_level) that’s in effect for a member may be greater than their standard_access_level
    • it is not possible to identify the above state via the API.

In the future, once effective_access_level becomes available, that state will be identifiable.

2 Likes

Hi @sasha_f , thanks for the updates—excited to test-drive it this week!

One question, and sorry if I’ve missed this context somewhere further up in this thread. Is there a way to explicitly turn off notifications via these new endpoints? Eg, in this screenshot I would assume the standard_access_level options you outlined (below) map to the Can edit and Can comment options in the GUI.

Do those values somehow also map to notification preferences (the second highlighted bit in that GUI screenshot)? Or is there another way to set/disable notifications via this endpoint?

Thanks again!

Looking into this for you! My gut says this is not available via the API at this time.

Okay, thanks for checking! Also, when trying to create a new Project Membership, I’m getting:

"message": "Please include a valid standard_access_level: ADMIN CONTRIBUTOR COMMENTER",

Tried sending both the documented write_all and the prompted CONTRIBUTOR values in upper/lower case. Do we (can we, if so?) need to opt in to this API update, to have access to these endpoints? That endpoint does work when we remove the standard_access_level altogether.

Also getting this, when attempting to hit the DELETE endpoint for memberships:

"message": "No matching route for request"

which endpoint are you using? Are you setting any Asana-Enable headers?