Create and Query iTwin Groups

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 creating and retrieving groups for a given iTwin. iTwin groups provide the ability to manage groups of users at one time. You can create groups on the Account iTwin to manage access across iTwins or create a group for an individual iTwin. Groups created on an individual iTwin are available only on that iTwin. For more information for managing access using the Account iTwin, see Managing access using the Account iTwin

Groups can contain individual users and can also reference Bentley Identity Management System (IMS) groups. By referencing an IMS group, you can manage groups of individuals in your Active Directory, while providing them access to iTwin Platform using role assignments. IMS groups are created and controlled on the team level, and can be accessed here through Bentley's User Management service. Only Accout Administrators, Co-Administrators, and Group Administrators will have access to the User Management Service. More information about creating and maintaining IMS groups can be found here.

By the end of this walk-through, you will be able to utilize the API endpoints in order to create and retrieve a list of iTwin groups.

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 IMS group. IMS (Identity Management System) groups are created and controlled on the team level, and can be accessed here through Bentley's User Management service. Only Accout Administrators, Co-Administrators, and Group Administrators will have access to the User Management Service. More information about creating and maintaining IMS groups can be found here.

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.

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.

Implement Authorization Code Flow in the application

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

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

Grab a user token from the iTwins documentation page

  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. Create iTwin Group

The Create iTwin group endpoint is used to create iTwin groups. After a group is created, users and IMS groups can be added.

The iTwin id from an existing iTwin (see create and query iTwins guide) is required to create a group. A name and description are required in the POST body.

The POST call will return a new group instance. The returned group id along with the iTwin id will be used to add users and IMS groups in the next step.

Request Syntax


,
http
POST https://api.bentley.com/accesscontrol/itwins/{id}/groups 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
{
      "name": "Engineers",
      "description": "This is a group for engineers",
    }
,

Response Headers


,
http
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-v2:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 74e263d7-ded7-45a5-8347-ca1f98ffab86
x-itwinplatform-media-type: bentley.itwin-platform.v2
x-itwinplatform-region: East US
,

Response Body


,
json
{
          "group": {
              "id": "d0ec803b-de9a-41cd-9d97-c8edddd4cb0d",
              "name": "Engineers",
              "description": "This is a group for engineers",
              "contextId": "a9c999c9-5516-4ea0-adc3-28238c02b18e",
              "users": [],
              "imsGroups": []
          }
      }

4. Update iTwins Groups Using the iTwin Id and Group Id

To assign users and imsGroups, the group needs to be updated. iTwin id and group id are required. The POST body should contain a list of users and imsGroups.

IMS groups are created and controlled on the team level, and can be accessed here through Bentley's User Management service. Only Accout Administrators, Co-Administrators, and Group Administrators will have access to the User Management Service. More information about creating and maintaining IMS groups can be found here.

The response will contain the group details along with the list of users and imsGroups added.

Request Syntax


,
http
PATCH https://api.bentley.com/accesscontrol/itwins/{id}/groups/{groupId} 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
{
      "name": "A new Group name",
      "description": "A new Group description",
      "imsGroups": [
        "IMS Engineers"
      ],
      "users": [
          "John.Doe@bentley.com"
      ]
}
,

Response Headers


,
http
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-v2:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: f16d2765-4a9c-40a4-995e-bd7c6b8b8d4a
x-itwinplatform-media-type: bentley.itwin-platform.v2
x-itwinplatform-region: East US
,

Response Body


,
json
{
  "group":{
    "id":"10a2d277-ea41-4e81-b309-f7a9aea09d51",
    "name": "A new Group name",
    "description": "A new Group description",
    "contextId": "a9c999c9-5516-4ea0-adc3-28238c02b18e",
    "imsGroups": [
      "IMS Engineers"
    ],
    "users": [
        "John.Doe@bentley.com"
    ]
  }
}

5. Query for Groups using the iTwin Id

iTwin Id can be used to retrieve a list of iTwin groups.

The API will return a list of groups for a given iTwin.

Request Syntax


http
GET https://api.bentley.com/accesscontrol/itwins/{id}/groups 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-type: application/json
date: Mon, 29 Aug 2022 19:24:14 GMT
request-context: appId=cid-v2:7a353d36-9a8b-423e-965e-9d7f51324584
vary: Accept-Encoding
x-correlation-id: 260678e5-0244-413d-bc60-f6dac19fd450
x-itwinplatform-media-type: bentley.itwin-platform.v2
x-itwinplatform-region: East US
x-rate-limit-limit: 1s
x-rate-limit-remaining: 49
x-rate-limit-reset: 2022-08-29T19:24:15.3864257Z

Response Body


json
{
      "groups": [
          {
              "id": "149d0860-39e9-4ae9-9b05-0b5dcedd2d4b",
              "name": "Engineers",
              "description": "This is a group of engineers",
              "contextId": "a9c999c9-5516-4ea0-adc3-28238c02b18e",
              "imsGroups": [
                "IMS Engineers"
              ],
              "users": [
                  "John.Doe@bentley.com"
              ]
          },
          {
              "id": "d0ec803b-de9a-41cd-9d97-c8edddd4cb0d",
              "name": "iTwin Administrators",
              "description": "This is a group of administrators for the iTwin",
              "contextId": "a9c999c9-5516-4ea0-adc3-28238c02b18e",
              "users": [],
              "imsGroups": ["IMS Admins"]
          }
      ]
  }