Introduction
This tutorial shows how to authorize a service application to manage iTwin level webhooks. iTwin level webhooks require the webhooks_maintainer permission to be assigned to them on the iTwin.
In this tutorial, we first create a role, then add the webhooks_maintainer permission to it. Next, we add the service application to the iTwin with this newly created role. If the service application is already a member of the iTwin, we update its role.
Prerequisites
You will need the following to complete this tutorial:
- Register your own Service Application on the iTwin Platform. Steps to register a Service Application can be found here.
- Have an existing iTwin. If you are affiliated with an Organization, you 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.
- Permissions to assign to a role. To see the list of available permissions, see get all permissions.
1. Create a role
First, create a role. Use the Create iTwin role endpoint to create iTwin roles.
The POST call returns a new iTwin Role. The returned id (the role id), along with the iTwinId, will be used to add permissions in the next step.
Request
Send a POST request to the /accesscontrol/itwins/{id}/roles endpoint with a valid iTwin Id to create a role:
- Include an Authorization header with a valid Bearer token.
- Provide the
iTwinIdfrom an existing iTwin (see create and query iTwins guide).
Request Body
The request body is defined in the Create iTwin role documentation.
To create an iTwin role, set the following properties:
displayNamedescription
{
"displayName": "iTwin Webhooks Maintainer",
"description": "The iTwin Webhooks Maintainer Role"
}
Response
On a successful request, the operation returns HTTP status code 201 (Created), indicating that the iTwin role has been successfully created.
{
"role": {
"id": "faa3dca1-a901-4659-9da1-d9f29ddcc288",
"displayName": "iTwin Webhooks Maintainer",
"description": "The iTwin Webhooks Maintainer Role"
}
}
2. Add permission to role
Once the role is created, add the webhooks_maintainer permission to it. Use the Update iTwin role endpoint to update iTwin roles, including adding permissions.
The POST call returns the updated role, including the new list of permissions.
Request
Send a POST request to the /accesscontrol/itwins/{id}/roles/{roleId} endpoint with a valid iTwin Id to create a role:
- Include an Authorization header with a valid Bearer token.
- Provide the
iTwinIdfrom an existing iTwin (see create and query iTwins guide). - Provide the
roleIdfrom a created iTwin role from the previous step.
Request Body
The request body is defined in the Update iTwin role documentation.
When updating a role, all properties are optional. For this tutorial, we will set the following property:
permissions
{
"permissions": ["webhooks_maintainer"]
}
Response
On a successful request, the operation returns HTTP status code 200 (OK), indicating that the iTwin role has been successfully updated.
{
"role": {
"id": "faa3dca1-a901-4659-9da1-d9f29ddcc288",
"displayName": "iTwin Webhooks Maintainer",
"description": "The iTwin Webhooks Maintainer Role",
"permissions": ["webhooks_maintainer"]
}
}
3. Add or Update Service Application to iTwin
After adding the permission to the new role, you need to either add the Service Application to the iTwin as a user member or update its roles to include the newly created role.
Add Service Application to iTwin
The Add iTwin user member endpoint is used to add user members to a given iTwin.
Request
Send a POST request to the /accesscontrol/itwins/{id}/members/users endpoint with a valid iTwin Id to add a user member:
- Include an Authorization header with a valid Bearer token.
- Provide the
iTwinIdfrom an existing iTwin (see create and query iTwins guide). - Register your own Service Application on the iTwin Platform. Steps to register a Service Application can be found here.
Request Body
The request body is defined in the Add iTwin user member documentation.
When adding user members, the following properties are required:
email: the generated email of your service application can be found on the My Apps page in My Apps > App Name.roleId: the id of the role we created earlier.
{
"members": [
{
"email": "SERVICE_APPLICATION@apps.imsoidc.bentley.com",
"roleIds": ["faa3dca1-a901-4659-9da1-d9f29ddcc288"]
}
]
}
Response
On a successful request, the operation returns HTTP status code 201 (Created), indicating that the Service Application has been successfully added to the iTwin.
{
"members": [
{
"id": "99cf5e21-735c-4598-99eb-fe3940f96353",
"email": "SERVICE_APPLICATION@apps.imsoidc.bentley.com",
"givenName": "SERVICE_APPLICATION",
"surname": "LastName",
"organization": null,
"roles": [
{
"id": "faa3dca1-a901-4659-9da1-d9f29ddcc288",
"displayName": "iTwin Webhooks Maintainer",
"description": "The iTwin Webhooks Maintainer Role"
}
]
}
],
"invitations": []
}
Update roles of the Service Application
If the Service Application is already a member of the iTwin, you need to update its roles to include the newly created role. The Update iTwin user member endpoint is used to update user members' roles for a given iTwin.
Request
Send a PATCH request to the /accesscontrol/itwins/{id}/members/users/{memberId} endpoint with a valid iTwin Id and member Id to update a member's role:
- Include an Authorization header with a valid Bearer token.
- Provide the
iTwinIdfrom an existing iTwin (see create and query iTwins guide). - The
memberIdcan be found in the response of the Get iTwin user members endpoint.
Request Body
The request body is defined in the Update iTwin user member documentation.
When updating a user member, the following properties are required:
roleIds
{
"roleIds": ["faa3dca1-a901-4659-9da1-d9f29ddcc288"]
}
Response
On a successful request, the operation returns HTTP status code 200 (OK), indicating the user member's iTwin roles have been updated.
{
"member": {
"id": "99cf5e21-735c-4598-99eb-fe3940f96353",
"roles": [
{
"id": "faa3dca1-a901-4659-9da1-d9f29ddcc288",
"displayName": "iTwin Webhooks Maintainer",
"description": "The iTwin Webhooks Maintainer Role"
}
]
}
}