Updating User Permissions

Update user permissions using the MTM API.

Overview

As an administrator, you can manage users in your Workspace programmatically using the Multi-Tenancy Management (MTM) REST API. In this guide, you will learn how to update user permissions through the API.

Permissions define the user permission 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.

Learn more about managing users in our user documentation.

Authentication

To learn how to authenticate to our APIs, see Authentication to LeanIX Services.

In all API requests listed on this page, replace {ACCESS_TOKEN} with your access token.

API Reference

You can view the reference documentation for the MTM API in the OpenAPI Explorer. The base URL differs for different customers, so make sure to use the right link.

To navigate to the OpenAPI Explorer from your Workspace, on the user menu, select About LeanIX, and then select Browse API. In the OpenAPI Explorer, select MTM in the upper-right corner.

Step 1: Retrieve User Permissions for a Workspace

To update a user permission, you need to get a list of permissions first.

To retrieve all user permissions for a Workspace, make a GET request to the following endpoint:

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

You can filter results for a specific user by providing their user ID or email address.

ParameterParameter TypeData TypeRequired?Description
idPathStringThe ID of the Workspace to retrieve user permissions for. To get your Workspace ID, on the user menu, click Administration, and then go to API Tokens. Copy the WorkspaceId value.
emailQueryStringThe email address of the user to search for.
qQueryStringQuery string to filter data for a specific user. You can specify a user's first name, last name, role, or other details. This parameter is not used in the example.
statusQueryStringThe status of the user to search for, such as ACTIVE, INVITED, or ARCHIVED. This parameter is not used in the example.

Example request:

curl --request GET \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/workspaces/e1937ae6-05d4-4e43-{...}-565e7d80b82c/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": [
    {
      "id": "04259076-8cbc-418e-{...}-20144d5d8bda",
      "user": {
        "id": "bdba4b5d-2d63-49ef-{...}-045f020294bb",
        "account": {...},
        "userName": "[email protected]",
        "email": "[email protected]",
        "role": "ACCOUNTUSER",
        "status": "ACTIVE",
        ...
      },
      "workspace": {...},
      "workspaceId": "e1937ae6-05d4-4e43-a3b5-565e7d80b82c",
      "role": "MEMBER",
      "status": "INVITED",
      "lastLogin": null,
      ...
    }
  ]
}

Step 2: Update a User Permission

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

https://{SUBDOMAIN}/services/mtm/v1/permissions

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

There are two main use cases:

  • Updating the user role. Set role to one of the following values: VIEWER, MEMBER, or ADMIN.
  • Updating the user status. Set status to:
    • ARCHIVED — to archive a user. You can't remove users from a Workspace. You can only archive them.
    • ACTIVE — to make an archived user account active. You can't change the status from INVITED to ACTIVE.

As an example, let's change the user role to ADMIN.

Example request:

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/permissions \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer eyJhbGciOiJSUz{...}' \
  --data '{
      "id": "04259076-8cbc-418e-{...}-20144d5d8bda",
      "user": {
        "id": "bdba4b5d-2d63-49ef-a087-045f020294bb",
        "account": { ... },
        "userName": "[email protected]",
        "email": "[email protected]",
        "role": "ACCOUNTUSER",
        "status": "ACTIVE",
        ...
      },
      "workspace": { ... },
      "workspaceId": "e1937ae6-05d4-4e43-{...}-565e7d80b82c",
      "role": "ADMIN",
      "status": "INVITED",
      "lastLogin": null,
      ...
    }'

For a successful request, you get a 200 OK response code. The response body contains the updated user data and additional details about the request.

Example response:

{
   "status": "OK",
   "type": "Permission",
   "errors": [],
   "total": 0,
   "data": {
      ...
      "id": "704259076-8cbc-418e-{...}-20144d5d8bda",
      "user": {...},
      "workspace": {...},
      "workspaceId": "e1937ae6-05d4-4e43-{...}-565e7d80b82c",
      "role": "ADMIN",
      "status": "INVITED",
      ...
   }
}