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.

Info

Skill level:

Basic

Duration:

15 minutes

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 the TryIt 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

To build an application on the iTwin Platform, you will need to register a client.

Click the Register Application button to automatically register a client for this quick start. You can find registered application in My apps page.

Application registration process


To register a client:

  1. Go to the iTwin Platform home page
  2. Click the Sign In button and sign-in using your Bentley account credentials
    • If you have not already registered, click Register now and complete the registration process.
  3. Click on your user icon and navigate to the My Apps page
  4. Click the Register New button
  5. Give your application a Name
  6. Select the Administration API
  7. Select application type SPA (Single Page Web Application)
  8. Enter Redirect URL
    • For this tutorial use https://localhost:3000
  9. Leave post logout redirect URIs empty.
  10. Click the Save button
Note the Client ID that is generated during the registration process. You will need this in a later step.

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.

Implement Authorization Code Flow in the application


Here you can use Client ID generated from previous registration step.

Grab a user token from Api reference “Try it” Section


  1. Go here
  2. Click Try it button.
  3. Under the Authorization section, select authorizationCode from the dropdown.
  4. After the signin popup closes, the Authorization header with token value should be visible beneath the HTTP request dropdown.
  5. Copy & paste the Authorization value for this tutorial.
Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

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 retruned role id along with the project id will be used to add permissions in the next step.

Request Syntax


1 POST https://api.bentley.com/projects/{id}/roles/ HTTP/1.1

Request Headers


1 2 3 Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN

Request Body


1 2 3 4 { "displayName": "Project Administrator", "description": "Project Administrator" }

Response Headers


1 2 3 4 5 6 7 8 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


1 2 3 4 5 6 7 8 { "role": { "id": "14b391cf-ce9e-43d3-8fee-c49e57c2680d", "displayName": "Project Administrator", "description": "A description of Project Administrator", "permissions": [] } }

4. Update Project Role Using the Proejct 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


1 PATCH https://api.bentley.com//projects/{id}/roles/{roleId} HTTP/1.1

Request Headers


1 2 3 Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN

Request Body


1 2 3 { "permissions": ["administration_invite_member", "administration_manage_roles", "administration_remove_member"] }

Response Headers


1 2 3 4 5 6 7 8 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


1 2 3 4 5 6 7 8 { "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


1 GET https://api.bentley.com/projects/d9102abc-abfc-4617-b19d-804896064cea/roles HTTP/1.1

Request Headers


1 2 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN

Response Headers


1 2 3 4 5 6 7 8 9 10 11 12 13 14 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


1 2 3 4 5 6 7 8 9 10 11 12 13 { "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


1 POST https://api.bentley.com/projects/2ff085cf-c255-46a9-9c6f-7d88f59bcbf9/members HTTP/1.1

Request Headers


1 2 3 Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN

Request Body


1 2 3 4 5 6 { "email": "John.Doe@bentley.com", "roleNames": [ "Project Administrator" ] }

Response Headers


1 2 3 4 5 6 7 8 9 10 11 12 13 14 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


1 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


1 GET https://api.bentley.com/projects/{id}/members HTTP/1.1

Request Headers


1 2 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN

Response Headers


1 2 3 4 5 6 7 8 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


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "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" } } }

More resources that you may like

iTwin Project Sample App

Sample application that uses the Projects API to create roles and add users to projects.