LeanIX - Product Documentation

Welcome to the LeanIX Product Documentation. Here you will find all the basic information you need to start working with LeanIX. We provide you with well-structured information on how to get more out of LeanIX, best-practices and use-case specific guidelines. Feel free to spread this product documentation in your company and use it as a common information source to answer your colleaguesโ€™ most urgent questions.

Get Started

User Management

Overview

This page gives you a short overview 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 Authentication.

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 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 property

Explaination

host.id

The UserId of the user that is acting. You can find your UserId at Administration->API Tokens.

workspace.id

The WorkspaceId of your workspace you can find at Administration->API Tokens.

permission.role

VIEWER, MEMBER or ADMIN

message

The 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 a 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[...]' \

Parameter

Explanation

workspace.id

The WorkspaceId of your workspace you can find at Administration->API Tokens.

email

Email to search for

q

Query string to search in user (first name, last name, role) - not shown in the example

status

Optional 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

Updated 25 days ago


User Management


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.