Manage User Members on iTwins

Introduction

This tutorial is for the Access Control API V2. To control the API version, see the API versions documentation

This tutorial will take you through the process of adding and retrieving user members for a given iTwin. Members are users which have been assigned a role, in turn giving them a set of permissions. Members can be assigned more than one role and the same role can be assigned to more than one member.

By the end of this walk-through, you will be able to utilize the API endpoints in order to invite users to an iTwin, and retrieve the list of iTwin user members.

Info

Skill level:

Basic

Duration:

15 minutes

Prerequisites

This tutorial assumes that you already have:

  • A tool, such as Postman that can be used to execute HTTP calls. These calls can also be made using the Try it out button in the API documentation.
  • If a user is affiliated with an Organization, the user must be an Organization Administrator to create an iTwin. 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.
  • An iTwin role. For more information on creating an iTwin role, please see the tutorial Create and Query iTwin Roles.

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 iTwins API and has iTwins:modify and iTwins:read scopes enabled.

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.

Follow this article to implement Authorization code workflow in your application.

Here you can use Client ID generated from previous registration step.
  1. Go here
  2. Click Try it out button.
  3. Under the Authorization section, select authorizationCode from the dropdown.
  4. After the sign in 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. Add iTwin User Member

The Add iTwin user member endpoint is used to add user members to a given iTwin.

iTwin id is a required parameter. The role id from an existing Role (see create and query iTwins roles guide) is required to create a add an user member to an iTwin. User email and the role id are required in the POST body.

The POST call will return the added user member(s).

Request Syntax


HTTP
POST https://api.bentley.com/accesscontrol/itwins/{id}/members HTTP/1.1

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v2+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body


JSON
{
  "members": [
    {
    "email": "John.Doe@bentley.com",
    "roleId": "806ac320-80be-489e-b95d-7d27752776a0"
    }
  ]
}

Response Headers


HTTP
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
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-v2:7a353d36-9a8b-423e-965e-9d7f51324584
vary: Accept-Encoding
x-correlation-id: d1999ea1-62bd-4e84-8e5d-1a8aac040de4
x-itwinplatform-media-type: bentley.itwin-platform.v2
x-itwinplatform-region: East US

Response Body


JSON
{
    "members": [
      {
        "id": "08a2ede0-fc7d-4f52-996e-e1047feb27e9",
        "email": "John.Doe@bentley.com",
        "givenName": "John",
        "surname": "Doe",
        "organization": "Bentley Systems Inc",
        "roles": [{
            "id": "0af949d5-af90-4eed-84e0-d4d860f723d0",
            "displayName": "iTwin Administrator",
            "assignedDateTime": "2022-08-29T18:05:19.537846"
        }]
    }]
}

4. Query for User Members using the iTwin Id

The Id query parameter can be used to retrieve a list of user members using the iTwin Id.

The api will return a list of user members for the given iTwin.

Request Syntax


HTTP
GET https://api.bentley.com/accesscontrol/itwins/{id}/members HTTP/1.1

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN

Response Headers


HTTP
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-v2:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 7a199ff9-317f-4d4f-ba82-70ba25f31d32
x-itwinplatform-media-type: bentley.itwin-platform.v2
x-itwinplatform-region: East US

Response Body


JSON
{
    "members": [{
        "id": "56c58c0c-28a9-4cd2-b50b-102e33b657f2",
        "email": "Jane.Doe@example.com",
        "givenName": "Jane",
        "surname": "Doe",
        "organization": "Example Inc",
        "roles": [{
            "id": "56e96811-6d6e-4418-a78f-a7f5933e6ed4",
            "displayName": "iTwin owner",
            "assignedDateTime": "2021-09-14T19:41:29.913"
        }]
    }, {
        "id": "54d1cc67-7900-47cd-8135-b6eaabf5c703",
        "email": "John.Doe@example.com",
        "givenName": "John",
        "surname": "Doe",
        "organization": "Example Inc",
        "roles": [{
            "id": "0af949d5-af90-4eed-84e0-d4d860f723d0",
            "displayName": "iTwin Administrator",
            "assignedDateTime": "2022-08-29T18:05:19.537846"
        }]
    }],
  "_links":{
    "self":{
      "href":"https://api.bentley.com/accesscontrol/efa557b7-ecd7-4a60-9589-2acce11f6cc9/members?$top=100&$skip=0"
    }
  }
}

More resources that you may like

Tutorial for creating and querying iTwins.
Tutorial for creating and querying iTwin roles.