Updating User Permissions

Overview

This guide provides instructions on how to update user permissions through the Multi-Tenancy Management (MTM) REST API.

Permissions define the user status, role, and other attributes related to authorization for each workspace. Each user can only have a single permission for each workspace. Each attribute on the permission can only be set once. Some attributes, such as role, only allow a single value. Other attributes, such as customerRoles, allow multiple values. To learn more about managing users, see Users.

Prerequisites

Before you start, do the following:

Get an API token by creating a technical user with admin permissions. For instructions, see Create a Technical User.
Learn how to authenticate to SAP LeanIX services. For details, see Authentication to SAP LeanIX Services.
Get the ID of your workspace. To do that, in the administration area, navigate to the API Tokens section, then copy the WorkspaceId value.

Step 1: Retrieve User Permissions

To update a permission, first retrieve a list of user permissions for a workspace. To do that, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/mtm/v1/workspaces/{id}/permissions

The following table lists the input parameters.

Parameter	Parameter Type	Data Type	Required	Description
`id`	Path	String	Required	The ID of the workspace to retrieve user permissions for.
`q`	Query	String	Optional	Query string to filter data for a specific user. You can specify the user's first name, last name, role, or other details.
`email`	Query	String	Optional	The email address of the user to search for.
`status`	Query	String	Optional	The status of the user to search for, such as `ACTIVE`, `INVITED`, or `ARCHIVED`.
`includeTechnicalUsers`	Query	Boolean	Optional	Determines whether to include technical users in the response.
`page`	Query	Integer	Optional	The page number to return in the response. The default value is `1`.
`size`	Query	Integer	Optional	The page size to return in the response. The default value is `30`. The maximum value is `100`.
`sort`	Query	String	Optional	A list of sorting parameters separated by commas.

Example request:

curl --request GET \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/workspaces/bdba4b5d-2d63-49ef-f8g4-045f020294bb/permissions?email=john.doe%40meshlab.de \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer {ACCESS_TOKEN}' \

Example response:

{
  "status": "OK",
  "type": "Permission",
  "errors": [],
  "total": 1,
  "data": [
    {
      "links": [...],
      "id": "04259076-8cbc-418e-5d8h-20144d5d8bda",
      "user": {
        "id": "f767b7a2-5dd8-423e-d7f4-f9ea34d36ce8",
        "account": {...},
        "userName": "[email protected]",
        "email": "[email protected]",
        "role": "ACCOUNTUSER",
        "status": "ACTIVE",
        ...
      },
      "workspace": {...},
      "workspaceId": "bdba4b5d-2d63-49ef-f8g4-045f020294bb",
      "role": "MEMBER",
      "status": "INVITED",
      "lastLogin": null,
      "invitedByUser": {...},
      "reviewedByUser": null,
      "customerRoles": null,
      "accessControlEntities": null,
      "ignoreBlacklist": false,
      "count": 0,
      "replayed": false,
      "active": false
    }
  ]
}

Step 2: Update User Permissions

To update user permissions, make a POST request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/mtm/v1/permissions

There are two main use cases for managing user permissions:

Updating the user role: Set role to one of the following values: VIEWER, MEMBER, or ADMIN. To learn more about these roles, see Standard User Roles.
Updating the user status: Set status to one of the following values:
- ARCHIVED: Archive a user. You can not remove users from a workspace, you can only archive their permissions.
- ACTIVE: Reactivate an archived user account. You can not change the status from INVITED to ACTIVE.

From the response body that you received in the previous step, copy the JSON object within the data array and modify relevant attributes.

The following table lists required parameters to be passed in the request body. Other parameters are optional.

Parameter	Parameter Type	Data Type	Required	Description
`user.id`	Body	String	Required	The ID of the user.
`workspace.id`	Body	String	Required	The ID of the workspace the user belongs to.
`role`	Body	String	Required	The role to be assigned to the user. Possible values: `VIEWER`, `MEMBER`, or `ADMIN`.
`status`	Body	String	Required	The status to be assigned to the user. Possible values: `ARCHIVED` or `ACTIVE`.

In the example request, we change the user role to ADMIN. The request body contains only required parameters.

Example request:

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/permissions \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer {ACCESS_TOKEN}' \
  --data '{
    "user": {
        "id": "f767b7a2-5dd8-423e-d7f4-f9ea34d36ce8"
     },
     "workspace": {
        "id": "bdba4b5d-2d63-49ef-f8g4-045f020294bb"
     },
     "role": "ADMIN",
     "status": "INVITED"
    }'

Example request body:

{
    "user": {
       "id": "f767b7a2-5dd8-423e-d7f4-f9ea34d36ce8"
    },
    "workspace": {
       "id": "bdba4b5d-2d63-49ef-f8g4-045f020294bb"
    },
    "role": "ADMIN",
    "status": "INVITED"
  }

Example response:

{
  "status": "OK",
  "type": "Permission",
  "errors": [],
  "total": 0,
  "data": {
    "links": [...],
    "id": "04259076-8cbc-418e-5d8h-20144d5d8bda",
    "user": {
      "id": "f767b7a2-5dd8-423e-d7f4-f9ea34d36ce8",
      "account": {...},
      "userName": "[email protected]",
      "email": "[email protected]",
      "role": "ACCOUNTUSER",
      "status": "ACTIVE",
      "technicalUser": false,
      "scimManaged": false,
      "transientUser": false,
      "links": [...],
      ...
    },
    "workspace": {...},
    "workspaceId": "bdba4b5d-2d63-49ef-f8g4-045f020294bb",
    "role": "ADMIN",
    "status": "INVITED",
    ...
  }
}