Manage Access Controls for your iTwin member using iTwin roles and permissions.

access-control

# Access Control API

The Access Control API provides a full encompassing suite of functionality to manage access on your digital twins. With this API, you can manage your digital twin's members and each member's permissions on the digital twin.

## Role-Based Access Control

The Access Control API is built following role-based access control (RBAC) principles, which is an approach to authorizing users. RBAC is defined around roles, permissions, and user role assignments. Permissions are the fundamental unit of approval to a resource. Roles are a grouping mechanism used to aggregate permissions, and are assigned to members of an iTwin. When a role is assigned to a user, the user is authorized to perform actions or access data based on those permissions.

## iTwin Permissions

iTwin access control is enforced by permissions. A permission grants access to an API function. In other words, all iTwin Platform APIs enforce the requirements of one or many permissions in order to call it's endpoints. The permissions required by an API endpoint are documented in the Authorization section of the API reference documentation.

## iTwin Roles

Roles are used to group permissions. Typically, the permissions grouped in a role are aligned with user personas and are assigned to those personas accordingly (e.g. iTwin Administrator). iTwin roles are defined on each iTwin and are scoped such that they must be assigned on that iTwin.

## iTwin Members

iTwin Members are the list of users which have been assigned a role on an iTwin. Each member has a list of permissions which have been assigned to them using roles, which permit them to perform actions on an iTwin.

### Service Applications

Service applications, used for machine-to-machine communication, may also be authorized to access resources for a given iTwin. Just like iTwin members, service applications have an identity. This allows you to authorize service applications using the same process as a normal iTwin member. The email for the application is found in the application registration portal. To authorize, a role must be assigned to the service application on an iTwin.


This information is included in every event the webhook will receive.

base-event

content

object

eventType

string

enqueuedDateTime

iTwinId

messageId

webhookId

Base Event

Event that gets triggered when a member is added to an iTwin.

accessControl.memberAdded.v1-event

Globally Unique Identifier of the member.

memberId

Globally Unique Identifier of the user added the member.

eventCreatedBy

memberType

Globally Unique Identifier of the role the member was assigned.

roleId

Name of the role the member was assigned.

roleName

accessControl.memberAdded.v1

Event that gets triggered when a member is removed from an iTwin.

accessControl.memberRemoved.v1-event

Globally Unique Identifier of the user who removed the member.

accessControl.memberRemoved.v1

Event that gets triggered when a role is assigned to a member.

accessControl.roleAssigned.v1-event

Globally Unique Identifier of the user who assigned the role.

accessControl.roleAssigned.v1

Event that gets triggered when a role is unassigned to a member.

accessControl.roleUnassigned.v1-event

Globally Unique Identifier of the user who unassigned the role.

accessControl.roleUnassigned.v1

access-control-v2

---

Add new iTwin members

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_invite_member` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


add-iTwin-members

OAuth access token with scope `itwins:modify`

Authorization

Setting to `application/vnd.bentley.itwin-platform.v1+json` is recommended.

Accept

default

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

The user has insufficient permissions for the requested operation.

This response indicates that iTwin, email, or roles with specified ID were not found.

Invalid request to add new iTwin member. Member already exists in iTwin.

Invalid request to add new iTwin member. Request payload might be missing some of the required properties.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

---

Retrieves a specific member for a specified iTwin.

### Missing Users

When members are removed from the Bentley Identity Management System, they are not automatically removed from the iTwin. Therefore, it is possible to have a situation where the user is no longer valid, yet they are still a member of the iTwin. When this happens, the member will be returned from this API endpoint with the follow values:
```
{
    "id": <memberId>,
    "email": null,
    "givenName": null,
    "surname": null,
    "organization": null, 
    ...
}
```
You should account for this in your software if you do not want to show these users. 

#### Cleanup

The Access Control API will perform a once-a-week cleanup to remove these "Missing Users". You can rely on this automated clean-up if this timeline is sufficient. 

If not, you can use the [Remove iTwin Member](https://developer.bentley.com/apis/access-control/operations/remove-iTwin-member/) API (user the memberId) to remove the member from the iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the iTwin. Organization Administrator can also retrieve an iTwin member for any iTwin in their Organization.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


get-iTwin-member

OAuth access token with scope `itwins:read`

This response indicates that iTwin with specified ID was not found.

---

Retrieves a list of iTwin members and their roles assignments.

### Missing Users

When members are removed from the Bentley Identity Management System, they are not automatically removed from the iTwin. Therefore, it is possible to have a situation where the user is no longer valid, yet they are still a member of the iTwin. When this happens, the member will be returned from this API endpoint with the follow values:
```
{
    "id": <memberId>,
    "email": null,
    "givenName": null,
    "surname": null,
    "organization": null, 
    ...
}
```
You should account for this in your software if you do not want to show these users. 

#### Cleanup

The Access Control API will perform a once-a-week cleanup to remove these "Missing Users". You can rely on this automated clean-up if this timeline is sufficient. 

If not, you can use the [Remove iTwin Member](https://developer.bentley.com/apis/access-control/operations/remove-iTwin-member/) API (user the memberId) to remove the member from the iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the iTwin. Organization Administrator can also retrieve iTwin members for any iTwin in their Organization.

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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


get-iTwin-members

The [$skip](https://www.odata.org/getting-started/basic-tutorial/#topskip) query option requests the number of items in the queried collection that are to be skipped and not included in the result.

$skip

The [$top](https://www.odata.org/getting-started/basic-tutorial/#topskip) system query option requests the number of items in the queried collection to be included in the result. Value must be less or equal to 100.

$top

representation

---

Remove the specified member from the iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_remove_member` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


remove-iTwin-member

Specified iTwin member was successfully removed.

---

Update an iTwin member's role assignments

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_invite_member` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


update-iTwin-member

Invalid request to update member roles. Request payload might be missing some of the required properties.

---

Retrieves the list of all available permissions

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

No Authorization is required for this API call.

---


get-all-permissions

---

Retrieves a list of permissions the calling user has on a specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

No Authorization is required for this API call.

---

get-iTwin-permissions

---

Create a new iTwin role.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_manage_roles` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


create-iTwin-role

This response indicates the iTwin was not found.

Invalid request to create new iTwin role. Make sure request had required properties and does not pass in readonly properties.

InvalidiTwinRoleRequest

---

Delete the specified iTwin role.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_manage_roles` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


delete-iTwin-role

This response indicates iTwin or role was not found.

---

Retrieves the specified role for the specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_manage_roles` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


get-itwin-role

---

Retrieves a list of available user roles that are defined for a specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_manage_roles` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


get-iTwin-roles

---

Update the specified iTwin role.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have the `administration_manage_roles` permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given 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](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


update-iTwin-role

A iTwin role instance with the fields that should be updated.

Invalid request to update iTwin role. Make sure request had required properties and does not pass in readonly properties.

Overview - Access Control | iTwin Platform

This tutorial will guide you through the process of adding and removing owners on an iTwin

Manage iTwin Owners

This tutorial will guide you through the process of creating and querying roles on an iTwin

Create and Query iTwin Roles

This tutorial will guide you through the process of creating and querying groups on an iTwin

Create and Query iTwin Groups

This tutorial will guide you through the process of managing iTwin user members

Manage User Members on iTwins

This tutorial will guide you through the process of managing iTwin group members