Summary
- As described in [Change] Project team sharing is coming!, projects can now be directly shared with multiple teams!
- As the latest step in improving the Asana project permissions model, newly created projects will no longer have a containing team and the
project.team
field will benull
. - Previously created projects have been migrated so that the containing team is a member of the project.
- If you currently read the
project.team
field over the API, you’ll need to update your code to handle anull
value for this field and get information from other endpoints. (more details are below) - The
project.team
field can still be written to on create, but can no longer be modified on a project, since the meaning and resulting behavior is ambiguous. (see details below)
Who is affected
- Anyone using the API to organize projects by their containing team, including:
- Creating a project with a containing team
- Accessing all projects with the same containing team
Upcoming changes by endpoint
- Projects created after this change will no longer have a containing team and the
project.team
field will benull
. Theteam
field will be marked deprecated. - For existing projects, the containing team (previously set when the project was created) will be migrated to be a member of the project.
- To maximize backward compatibility, projects created before this change will continue to return a team gid in the
project.team
field until that team is no longer a member of the project. At that point,project.team
will returnnull
.
All endpoints used to fetch projects, including:
GET /projects/
GET /projects/{project_gid}
GET /workspaces/{workspace_gid}/projects
GET /teams/{team_gid}/projects
- The
team
field on newly created projects will be null. - Clients that read the team property will be notified of the deprecation via an Asana-Change header.
- Projects created before this change will continue to have a team set in the
project.team
field until that team is removed from the project. If the team is removed as a member of the project, the project.team field will becomenull
. - All API clients should be prepared to handle a
null
value forproject.team
{
"data": {
"name": "Project Name",
"resource_type": "project",
"gid": "12345",
"team": null, << team can now be null
"privacy_setting": "public"
}
}
GET /memberships
- This endpoint will be updated so that the
member
filter can be used to fetch all memberships for a team gid. - Previously,
parent
andmember
were both required, nowparent
will be optional. - If
parent
is absent, a newresource_subtype
must be provided. (project_membership
for projects)
GET /teams/{team_gid}/projects
- This endpoint will be deprecated.
GET /memberships
should be used instead to get all projects that have been shared with a given team. (see above) - To maximize backwards compatibility, this endpoint will continue to function, but will return the projects where the given team is a member (the same as GET /memberships described above).
POST /projects/
POST /teams/{team_gid}/projects
- The team property will be marked deprecated and no longer required.
- Setting a team gid on project creation will add that team as a member of the project with the
default_access_level
but the team field will be set tonull
. - POST /memberships should be used instead to add teams as members to a project.
PUT /projects/{project_gid}
- You will no longer be able to update the
project.team
field over the API. The meaning of that update will be ambiguous now that projects are not contained within a team and many teams can be a member of a project.
Timeline
- In 6 months (roughly April 2025), we expect to begin allowing the creation of projects with no containing team in the Asana website and the API. We will update this post as more precise timelines are available.
project.team
will be null for a newly created project- Previously created projects will continue to return a team gid until that team is removed as a member of the project. At that point,
project.team
will be null and cannot be reset.
Migration steps by use case
Fetching projects by team
- Use GET /memberships. Specify the team gid with the
member
filter along with aresource_subtype
ofproject_membership
.
GET /memberships?parent={team_gid}\&resource_subtype=project
Identifying which teams a project “belongs to”
- Projects no longer belong to a team. Ideally, stop reading and requesting the
project.team
field. - Instead, use the GET /memberships endpoints above and be prepared to handle multiple teams having access to a project, but no longer “owning” or containing the project.
- If you continue to use
project.team
, be prepared to catch and handle anull
value.
Sharing a project with a team (including on creation)
- Set
privacy_setting
topublic_to_workspace
orprivate
on create. - Use POST /memberships to add one or more teams as a member of the project and set their access levels.
- Use PUT /membership/{project_membership_gid} to update a team’s access level and DELETE /memberships/{project_membership_gid} to remove a team’s access.
Why we’re making this change
- Asana users will be more free to create projects without caring what team they’re in, and can assign teams as members later.
- This latest change simplifies the creation of private projects intended to only be shared with their direct members.
Let us know if you have questions or feedback about this planned change. We know changes like this can be disruptive, and we’re doing our best to minimize breakage while continuing to improve and evolve Asana projects.