Update User Permissions

Introduction

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 APIs.

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.

Use the following endpoint to retrieve all user permissions for a Workspace. You can filter results for a specific user by providing their user ID or email address.

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

👍

How do I get my {SUBDOMAIN} value?

Copy the subdomain value from your Workspace URL. Learn more about the base URL.

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

You get a response like the following:

{
  "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

Call the following endpoint to update user permissions within a Workspace:

POST 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.

Example Request

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

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": "john.[email protected]",
        "role": "ACCOUNTUSER",
        "status": "ACTIVE",
        ...
      },
      "workspace": { ... },
      "workspaceId": "e1937ae6-05d4-4e43-{...}-565e7d80b82c",
      "role": "ADMIN",
      "status": "INVITED",
      "lastLogin": null,
      ...
    }'

Example Response

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.

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