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