Hello! As we continue to adjust our project permissions model to better support sharing at scale, we want to give the developer community early notice about what changes to expect over the next year.
After the changes, Asana (and the API) will be able to support sharing that can scale down to projects that are private to a single member and scale up to projects that are accessible to an entire organization, with different groups of people that have different levels of access to that project. Weāre enabling this with three user-facing changes:
- new project sharing options - share a project with your entire organization (just launched!)
- project team sharing - share projects with entire teams! (and not just users)
- teamless projects - projects are no longer contained within a team
This update is focused on the project team sharing API changes weāre making. Weāve included the changes below along with an estimated timeline. Weāll keep this estimate up-to-date on a monthly basis going forward.
Preview of upcoming project team sharing changes
When we roll out project team sharing for a workspace, the following changes will take effect:
View and modify team memberships over the API
Our new /membership endpoints will allow you to fetch, create, or modify a team membership for a given project. Lists of project members will include teams and users.
Existing endpoints for adding and removing users to a project will be marked deprecated and no longer preferred. They will not be updated to allow adding team members to a project. However, they will not be removed as part of this release.
GET /memberships?parent={project_gid}
{
"data": [
{
"gid": "11111",
"member": {
"gid": "22222",
"name": "Melissa",
"resource_type": "user"
},
"access_level": "admin",
"resource_type": "membership",
"resource_subtype": "project_membership"
},
{
"gid": "33333",
"member": {
"gid": "44444",
"name": "Marketing Team",
"resource_type": "team"
},
"access_level": "editor",
"resource_type": "membership",
"resource_subtype": "project_membership"
}
]
}
Team information on project membership audit log events
project_member_added, project_member_removed, and project_member_access_level_changed audit log events related to project memberships may now include team information.
For example, the project_member_added event:
{
"data": [
{
"gid": "12345",
"created_at": "2024-01-01T00:00:00.000Z",
"event_type": "project_member_added",
"event_category": "access_control",
"actor": {
"actor_type": "user",
"gid": "11111",
"name": "Greg Sanchez",
"email": "gregsanchez@example.com"
},
"resource": {
"resource_type": "project",
"gid": "22222",
"name": "API Documentation Project"
},
"details": {
"added_resource": {
"resource_type": "team",
"gid": "33333",
"name": "Developer Relations Team"
}
},
"context": {
"context_type": "web",
"client_ip_address": "1.1.1.1",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
}
}
]
}
Special cases for projects in a private team
A projectās team field may be null when the team is private to you
A user might be added to a private project, but not the private team which contains the project. In this scenario, the team field on the project object may appear to be null.
In the next and final phase of project permissions enhancements, projects will no longer have an associated team and the team field will be deprecated completely. Weāll share more about that transition in the coming months.
Project duplication behavior change
The duplicate project endpoint will return an error if you try to duplicate a project in a team that is private to you. This is to prevent users from creating projects for private teams they are not a member of. To mitigate this, you can specify the gid of a team the user has access to in the team field of the request. (If you donāt specify a team, Asana will attempt to create the new project in the same team as the original project.)
POST /projects/{project_gid}/duplicate
{
"data": {
"name": "Duplicate project",
"team": "12345" // team gid the user has access to
}
}
The private_to_team project privacy setting will be removed
As we shared with the announcement of project privacy settings, the private_to_team privacy setting will be removed as we roll out project team sharing. You will still be able to create a project with privacy_setting set to private_to_team, but it will be converted to private_to_members with the containing team added as a direct member. Although this is now considered as public false the same users will have the same access (Note: If this change happens you will notice it in your response). Because of this we suggest that you use privacy_setting set to private and add the team to the project yourself.
Create a private project:
POST /projects/
{
"data": {
ā¦
āprivacy_settingā: āprivateā,
ā¦
}
}
Then explicitly share the project with the team and assign an access level:
POST /memberships/
{
"data": {
"member": "12345", // team gid
"parent": "98765", // project gid
"access_level": "editor"
}
}
Project stories and project membership events / webhooks for team sharing
- The
member_addedproject story may now include teams as members. More information about this here. - Webhooks / events for project memberships - When you add a member to a project it generates a project membership added / removed event. The formats of these events shouldnāt change, but events will also be generated when a team is added or removed from a project.
A projectās āmembersā field will be incomplete
The project members field will not be updated to start returning teams as members. Consequently, once team sharing is implemented, the project members field will be incomplete as it wonāt provide an accurate representation of who is on a project.
While we have no plans to remove the field, it is essentially deprecated and will be marked as such in the developer docs.
Timeline of changes
May 2024-July 2024:
Project Team Sharing begins rolling out along with these changes (details above)
- View and modify team memberships over the API
- Team information on project membership audit log events
- Special cases for projects in a private team (
nullteam field and duplicate project behavior change) - The
private_to_teamproject privacy setting will be removed - Project stories and project membership events / webhooks for team sharing
Later in 2024:
We will stop requiring a team on project creation. More to come here including more specific timeline!
FAQ
How will I know whether or not a workspace is part of the team sharing rollout?
We will return a 400 status code with the following body:
{
"errors": [
{
"message": "Team Project Memberships are currently not supported.",
"help": "For more information on API status codes and how to handle them, read the docs on errors: https://developers.asana.com/docs/errors"
}
]
}
What happens when a userās individual permissions conflict with their team permissions?
If there is a conflict between a userās explicit permission and the permission given to them through team membership, the user will be granted the higher access level.
For example, if a user is a viewer on a project, but is part of a team which has the editor access level, they will be given editor permissions to the project.
If you have any additional questions, donāt hesitate to ask! Please subscribe to this thread if you are interested in updates. We may have updates to FAQ and timelines.
Thanks,
John