Update a User’s Folder Permissions
This tutorial demonstrates how to update folder permissions for a user in BIM 360 Document Management. The steps include retrieving the user’s current permissions for the folder and updating permissions for the user.
For more infomation about folder permissions, see the Help documentation.
Before You Begin
- Register an app.
- Provision your app to acquire access to your BIM 360 account, to both BIM 360 Account Administration and Document Management.
- Acquire a 3-legged OAuth token or a 2-legged OAuth token with
account:read
account:write
data:read
anddata:write
scopes. - Find the account ID, the project ID, and the folder ID of the folder that you want to find the user’s permissions for, by following the initial steps of the Upload Files tutorial.
Step 1: Retrieve the User’s Folder Permissions
When updating permissions for a user, we recommend first checking which permissions have already been assigned to the user. Call GET permissions using the project ID and folder ID to get all permissions for the folder, including the user’s individual permissions, and the permissions of the companies and roles that were assigned to the folder.
To initially add a user to the folder, see Create Permissions
curl -X GET \
https://developer.api.autodesk.com/bim360/docs/v1/projects/5a9ac886-0441-44da-a64a-bbea5b1e2ba3/folders/urn%3Aadsk.wipprod%3Afs.folder%3Aco.hGZHbcx2QHufgVMs_IDFlg/permissions \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
[
{
"subjectId": "12ea2c20-1fde-43ad-b4ec-6d4c4ca84994",
"autodeskId": "WDF5NJDPVJUV",
"name": "Tom",
"email": "tom@autodesk.com",
"userType": "PROJECT_MEMBER",
"subjectStatus": "ACTIVE",
"subjectType": "USER",
"actions": [
"VIEW",
"DOWNLOAD",
"COLLABORATE"
],
"inheritActions": [
"VIEW",
"COLLABORATE"
]
},
{
"subjectId": "7cd13d3a-1b53-4747-b332-2252d2d19808",
"autodeskId": "28658742",
"name": "Architect",
"subjectStatus": "ACTIVE",
"subjectType": "ROLE",
"actions": [],
"inheritActions": [
"PUBLISH"
]
},
{
"subjectId": "43ed71b3-b739-470d-ac91-7f7110a9107c",
"autodeskId": "57634726",
"name": "Engineer",
"subjectStatus": "ACTIVE",
"subjectType": "ROLE",
"actions": [
"PUBLISH",
"VIEW",
"DOWNLOAD",
"COLLABORATE",
"EDIT"
]
}
]
Note the user’s individual permissions (actions
and inheritActions
). See the documentation for information about how to convert the actions into BIM 360 permission levels.
The complete list of the user’s permissions is the aggregate of the user’s individual permissions combined with the permissions of the company ("subjectType": "COMPANY"
) that was assigned to the user (if that company was also assigned to the folder), and the permissions of any roles ("subjectType": "ROLE"
) that were assigned to the user (if those roles were also assigned to the folder).
Check where the subjectType
is a COMPANY
or ROLE
, and note the subjectId
for the companies and roles, and then call GET projects/users to check whether any of the companies or roles were also assigned to the user. You will then have the complete set of permissions for the user for the folder: the user’s individual permissions, the user’s role permissions, and the user’s company permissions. For more details see the Retrieve a User’s Folder Permissions tutorial.
Step 2: Update the User’s Permissions
You can update the user’s permissions in a number of ways. We will describe the following options:
- Directly update the user’s permissions.
- Update permissions for a role or company (that had been assigned to the folder) that had been assigned to the user.
- Assign a role or company (that had been assigned to the folder) to the user.
Option 1: Update the user’s permissions directly
Call Update permissions using the project ID and folder ID to directly update the users’s permissions.
curl -X POST \
https://developer.api.autodesk.com/bim360/docs/v1/projects/5a9ac886-0441-44da-a64a-bbea5b1e2ba3/folders/urn%3Aadsk.wipprod%3Afs.folder%3Aco.hGZHbcx2QHufgVMs_IDFlg/permissions:batch-update \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '[
{
"subjectId": "12ea2c20-1fde-43ad-b4ec-6d4c4ca84994",
"subjectType": "USER",
"actions": [
"PUBLISH",
"VIEW",
"DOWNLOAD",
"COLLABORATE",
"EDIT"
]
}
]'
{
"results": [
{
"subjectId": "12ea2c20-1fde-43ad-b4ec-6d4c4ca84994",
"subjectType": "USER",
"actions": [
"PUBLISH",
"VIEW",
"DOWNLOAD",
"COLLABORATE",
"EDIT"
]
}
]
}
Option 2: Update permissions for a role or company
To update permissions for a role that was assigned to the user, call GET projects/users/:id, to get the list of IDs of roles that were assigned to the user, and call GET roles to find the role that corresponds to the role ID. In this example assume that the user was assigned an Architect
role (7cd13d3a-1b53-4747-b332-2252d2d19808
).
Call Update permissions using the project ID, folder ID, and role ID to assign the role to the folder. This will automatically update the user’s permissions.
curl -X POST \
https://developer.api.autodesk.com/bim360/docs/v1/projects/5a9ac886-0441-44da-a64a-bbea5b1e2ba3/folders/urn%3Aadsk.wipprod%3Afs.folder%3Aco.hGZHbcx2QHufgVMs_IDFlg/permissions:batch-update \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '[
{
"subjectId": "7cd13d3a-1b53-4747-b332-2252d2d19808",
"subjectType": "ROLE",
"actions": [
"PUBLISH",
"VIEW",
"DOWNLOAD",
"COLLABORATE",
"EDIT"
]
}
]'
{
"results": [
{
"subjectId": "7cd13d3a-1b53-4747-b332-2252d2d19808",
"subjectType": "ROLE",
"actions": [
"PUBLISH",
"VIEW",
"DOWNLOAD",
"COLLABORATE",
"EDIT"
]
}
]
}
Option 3: Assign a role or company to the user
To update permissions for a user by assigning a role (that had already been assigned to the folder) to the user, call GET permissions to check which roles had been assigned to the folder, call GET projects/users/:id to check which roles the user had been assigned, and, if you want to assign the role to the user, call PATCH projects/users/:id. This will automatically update the user’s permissions.
In this example, assume that you want to add an Engineer
(43ed71b3-b739-470d-ac91-7f7110a9107c
) role to the user.
curl -X PATCH \
https://developer.api.autodesk.com/hq/v2/accounts/99cfda26-86b4-4255-820f-2422116acc7c/projects/5a9ac886-0441-44da-a64a-bbea5b1e2ba3/users/12ea2c20-1fde-43ad-b4ec-6d4c4ca84994 \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"industry_roles": [
"7cd13d3a-1b53-4747-b332-2252d2d19808",
"43ed71b3-b739-470d-ac91-7f7110a9107c"
]
}'
{
"account_id": "99cfda26-86b4-4255-820f-2422116acc7c",
"project_id": "5a9ac886-0441-44da-a64a-bbea5b1e2ba3",
"company_id": "572c7a25-bf4b-4f21-bbe5-ff4a806be56e",
"email": "tom@autodesk.com",
"industry_roles": [
"7cd13d3a-1b53-4747-b332-2252d2d19808",
"43ed71b3-b739-470d-ac91-7f7110a9107c"
],
"user_id": "12ea2c20-1fde-43ad-b4ec-6d4c4ca84994"
}