Manage Project Team Members
Introduction
This tutorial will take you through the process of creating roles, adding team members, and retrieving team members for a given iTwin Project.
By the end of this walk-through, you will be able to utilize the API endpoints in order to create roles, add & assign permissions to the role, invite users to a project, and retrieve the list of project members.
Prerequisites
This tutorial assumes that you already have:
- A Project
- A tool such as
Postman
that can be used to execute http calls. These calls can also be made using theTryIt
button in the API documentation. - If a user is affiliated with an Organization, then the user must be an Organization Administrator in order to manage team members for a project. An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.
1. Register an Application
You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to configure Authorization Code Flow for your SPA application and get the correct access token.
Once generated, you will be shown a few lines of code under the button.
- IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. Displayed on application details page as Client ID.
- IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. Displayed on application details page as one of Redirect URIs.
- IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
- IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.
Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial. Make sure that your application is associated with Projects API and has
projects:modify projects:read
scopes enabled.
Single page application
Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.
2. Get a token
Before you can make a request to the APIs, a user token is needed. There are several ways to get it.
- Go here
- Click
Try it
button. - Under the
Authorization
section, selectauthorizationCode
from the dropdown. - After the sign in popup closes, the
Authorization
header with token value should be visible beneath theHTTP request
dropdown. - Copy & paste the
Authorization
value for this tutorial.
3. Create Project Role
The Create project role endpoint is used to create project roles. After role is created permissions can be assigned.
project id
is required to create a role. A display name
and description
are required in the POST body.
The POST call will return a new role instance. The returned role id
along with the project id
will be used to add permissions in the next step.
Request Syntax
POST https://api.bentley.com/projects/{id}/roles/ HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN
Request Body
{ "displayName":"Project Administrator", "description":"Project Administrator" }
Response Headers
HTTP/1.1 201 Created content-length: 203 content-type: application/json date: Wed, 30 Jun 2021 17:26:10 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 74e263d7-ded7-45a5-8347-ca1f98ffab86 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US
Response Body
{ "role":{ "id":"14b391cf-ce9e-43d3-8fee-c49e57c2680d", "displayName":"Project Administrator", "description":"A description of Project Administrator", "permissions":[ ] } }
4. Update Project Role Using the Project Id and Role Id
To assign permissions
Role needs to be updated. project id
and role id
are required. The POST body should contain list of permissions
.
The response will contain the role details along with the list of permissions assigned.
Request Syntax
PATCH https://api.bentley.com/projects/{id}/roles/{roleId} HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN
Request Body
{ "permissions":[ "administration_invite_member", "administration_manage_roles", "administration_remove_member" ] }
Response Headers
HTTP/1.1 200 OK content-length: 324 content-type: application/json date: Wed, 30 Jun 2021 18:17:39 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: f16d2765-4a9c-40a4-995e-bd7c6b8b8d4a x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US
Response Body
{ "role":{ "id":"10a2d277-ea41-4e81-b309-f7a9aea09d51", "displayName":"Project Administrator", "description":"A description of Project Administrator", "permissions":[ "administration_invite_member", "administration_manage_roles", "administration_remove_member" ] } }
5. Query for Roles using the Project Id
Project Id
can be used to retrieve a list of project roles.
The api will return a list of roles for a given project.
Request Syntax
GET https://api.bentley.com/projects/d9102abc-abfc-4617-b19d-804896064cea/roles HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Response Headers
HTTP/1.1 200 OK cache-control: must-revalidate, no-cache, private content-encoding: gzip content-type: application/json date: Wed, 30 Jun 2021 18:26:19 GMT etag: "QosNxHidwaC0+OqsAO9D5HQ9s0g=" mas-request-id: 280616fa-b078-4276-8cb6-b93b8e38433f mas-server: Bentley-WSG/4.0.12,Bentley-WebAPI/2.9 pragma: no-cache request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 vary: Accept-Encoding x-correlation-id: 06f3046a-5973-4571-b09b-747cbdddf2c1 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US
Response Body
{ "roles":[ { "id":"10a2d277-ea41-4e81-b309-f7a9aea09d51", "displayName":"Project Administrator", "description":"A description of Project Administrator", "permissions":[ "administration_invite_member", "administration_manage_roles", "administration_remove_member" ] } ], "_links":{ "self":{ "href":"https://api.bentley.com/projects/d9102abc-abfc-4617-b19d-804896064cea/roles?$skip=0&$top=100" } } }
6. Add Project Team Member
The Add project team member endpoint is used to add team members to a given project.
project id
is a required parameter. User email
and list of role names
are required in the POST body.
The POST call will only return the headers.
Request Syntax
POST https://api.bentley.com/projects/2ff085cf-c255-46a9-9c6f-7d88f59bcbf9/members HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN
Request Body
{ "email":"John.Doe@bentley.com", "roleNames":[ "Project Administrator" ] }
Response Headers
HTTP/1.1 201 Created cache-control: must-revalidate, no-cache, private content-encoding: gzip content-type: application/json date: Wed, 30 Jun 2021 19:30:40 GMT location: https://api.bentley.com/projects/2ff085cf-c255-46a9-9c6f-7d88f59bcbf9/members/56c58c0c-28a9-4cd2-b50b-102e33b657f2 mas-request-id: 744155a0-f492-44a9-b78d-3a8c516f53ee mas-server: Bentley-WSG/4.0.12,Bentley-WebAPI/2.9 pragma: no-cache request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 vary: Accept-Encoding x-correlation-id: d1999ea1-62bd-4e84-8e5d-1a8aac040de4 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US
Response Body
NO CONTENT
7. Query for Team Members using the Project Id
The Id
query parameter can be used to retrieve a list of team members using the Project Id
.
The api will return a list of team members for the given project.
Request Syntax
GET https://api.bentley.com/projects/{id}/members HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Response Headers
HTTP/1.1 200 OK content-length: 480 content-type: application/json date: Wed, 30 Jun 2021 19:46:24 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 7a199ff9-317f-4d4f-ba82-70ba25f31d32 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US
Response Body
{ "members":[ { "userId":"7caa33e9-9d4d-4446-be0e-4c012071e636", "email":"John.Doe@bentley.com", "givenName":"John", "surname":"Doe", "organization":"Bentley Systems Inc", "roles":[ "Team Member", "Project Administrator" ] } ], "_links":{ "self":{ "href":"https://api.bentley.com/projects/d9102abc-abfc-4617-b19d-804896064cea/roles?$skip=0&$top=100" } } }