User Management

Overview

This page gives you a short overview of how to use our Multi-tenancy manager (MTM) API to do the user management in your Workspace programmatically. An API token is needed to authenticate, for details see Technical User.

Get new users into your Workspace

As you might know, you can add a new user to your Workspace using the "+Invite"-button at the top right corner of the LeanIX web app. The following example shows how to do this by a POST to the /idm/invite of our MTM API.

Endpoint for US customers:
endpoint

Endpoint for EU customers:
endpoint

curl --request POST \
  --url https://<Your Domain Here>.leanix.net/services/mtm/v1/idm/invite \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer eyJhbGciOiJSUz[...]' \
  --data '{
  "host": {"id": "e0feed40-442f-494f-a2b9-bb7f75c54d89"},
  "user": {"email": "[email protected]"}, 
  "workspace": {"id": "c4176501-e85c-4629-b1a8-de0d8bf15a08"}, 
  "permission": {"role": "MEMBER"}, 
  "message":"I would like to invite you to LeanIX. LeanIX is a tool to manage our IT Landscape in a simple, yet effective way. Please use the link below to join my workspace.\n\nThank you,\nPeter"
  }'
Payload propertyExplaination
host.idThe UserId of the user that is acting. You can find your UserId at Administration->API Tokens.
workspace.idThe WorkspaceId of your workspace you can find at Administration->API Tokens.
permission.roleVIEWER, MEMBER or ADMIN
messageThe body of the email that is sent to the invitee. A header and the link to the Workspace is automatically added to the email.
If you omit the property message then a default body is used.

In cases where you do not want to send any notifications at all you can add the query parameter silent=true to your request. It would then become:

curl --request POST \
  --url https://app.leanix.net/services/mtm/v1/idm/invite?silent=true \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer eyJhbGciOiJSUz[...]' \
  --data '{
  "host": {"id": "e0feed40-442f-494f-a2b9-bb7f75c54d89"}, 
  "user": {"email": "[email protected]"}, 
  "workspace": {"id": "c4176501-e85c-4629-b1a8-de0d8bf15a08"}, 
  "permission": {"role": "MEMBER"}
  }'

Update permission

To update permission, you need to fetch it first. The /workspaces/getPermissions allows you to query all workspace permissions, e.g. by a user name or mail address.

Endpoint for US customers:
endpoint

Endpoint for EU customers:
endpoint

curl --request GET \
  --url https://<Your Domain Here>.leanix.net/services/mtm/v1/workspaces/e1937ae6-05d4-4e43-a3b5-565e7d80b82c/permissions?email=john.doe%40meshlab.de \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer eyJhbGciOiJSUz[...]' \
ParameterExplanation
workspace.idThe WorkspaceId of your workspace you can find at Administration->API Tokens.
emailEmail to search for
qQuery string to search in user (first name, last name, role) - not shown in the example
statusOptional status to search for (e.g. ACTIVE, INVITED, ARCHIVED) - not shown in the example

You get a result like the following:

{
  "status": "OK",
  "type": "Permission",
  "errors": [],
  "total": 1,
  "data": [
    {
      "id": "04259076-8cbc-418e-a5ed-20144d5d8bda",
      "user": {
        "id": "bdba4b5d-2d63-49ef-a087-045f020294bb",
        "account": { ... },
        "userName": "[email protected]",
        "email": "[email protected]",
        "role": "ACCOUNTUSER",
        "status": "ACTIVE",
        ...
      },
      "workspace": { ... },
      "workspaceId": "e1937ae6-05d4-4e43-a3b5-565e7d80b82c",
      "role": "ADMIN",
      "status": "INVITED",
      "lastLogin": null,
      ...
    }
  ]
}

📘

Important

The endpoint returns a list of permission. Make sure to filter for the correct one, e.g. by mapping the exact mail address against the returned permissions.

To update the permission, you need to copy the JSON object within the "data" array and modify the relevant attributes. There are two major use cases:
a) Update the role: Set role to ADMIN, MEMBER, USER
b) Update the status: Set status to ACTIVE or ARCHIVED

The updated JSON is then sent back to the MTM API /permissions endpoint, e.g.

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

📘

Important

Note that there is always only a single permission per workspace for each user.

Archive permission

See the Update Permission section above for details. This change can be accomplished by simply setting:

status=ARCHIVED