Upcoming changes that impact getting and setting memberships and access levels

Community Forum English Developers & API Platform News
#1

tl;dr:

  • endpoints for membership management are being refactored and combined (e.g.,
    GET /portfolio_memberships & GET /team_memberships → GET /memberships
  • the new <METHOD> /memberships endpoint has a new associated resource
  • objects that support members will now support Teams as members, in addition
    to Users
    • new objects with this membership model will be added over time
  • https://developers.asana.com/docs will be updated soon
  • opt-in to this starting 2022-02-06

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.

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": "<User or Team resource>",
  "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": "<User resource>",
  "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-03-10 Opt-Out available
2023-04-19 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. ↩︎

4 Likes
API Changelog
API Changelog
API Changelog
#2

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:

#3

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

2 Likes
#4

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)
2 Likes
#5

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!

#6

: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!

1 Like
#7

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

#8

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