Access Tokens Required for SCIM

To configure SCIM, you need a long-lived access token. In this guide, you’ll learn how to obtain, retrieve, and deactivate access tokens through the MTM REST API. To view reference documentation for the MTM API, navigate to the OpenAPI Explorer.

Obtaining a Short-Lived Access Token

To obtain a long-lived access token required for the SCIM integration, you need a short-lived access token. The long-lived token inherits the user role from the short-lived token. The Technical User through which you request a short-lived token must have the ACCOUNTADMIN role.

To obtain a short-lived access token, follow these steps:

1. Create a Technical User with the Admin permission role. Save the API token that appears. For instructions, see Create a Technical User.

2. Request the ACCOUNTADMIN role for the Technical User by submitting a ticket to SAP LeanIX Support. In the request, provide the name of the Technical User.

3. Using the API token of the Technical User, obtain a short-lived access token. Replace the following placeholders with your values:

   • {SUBDOMAIN}: Your SAP LeanIX subdomain. You can copy the subdomain value from the URL of your workspace.
   • {API_TOKEN}: The API token that you obtained by creating a Technical User.

Example request:

curl --request POST https://{SUBDOMAIN}.leanix.net/services/mtm/v1/oauth2/token \
  -u apitoken:{API_TOKEN} \
  --data grant_type=client_credentials

A short-lived access token is returned in the access_token attribute in the response. The token is valid for 3600 seconds.

Save the token. You need it to obtain a long-lived access token.

Example response:

{
   "scope": "",
   "expired": false,
   "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA",
   "token_type": "bearer",
   "expires_in": 3599
}

Obtaining a Long-Lived Access Token

A long-lived access token is required for the SCIM integration. This token does not have an expiration date. It's valid until deleted or deactivated.

Before proceeding, obtain a short-lived access token. For instructions, see Obtaining a Short-Lived Access Token.

To obtain a long-lived access token, make a POST request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens

The following table lists parameters that you should pass in the request body.

The following example request contains placeholders that you should replace with your values.

• {SUBDOMAIN}: Your SAP LeanIX subdomain. You can copy the subdomain value from the URL of your workspace.
• {SHORT_LIVED_ACCESS_TOKEN}: Short-lived access token that you retrieved in the previous step.
• {WORKSPACE_ID}: The ID of your workspace. To get your workspace ID, in the administration area, navigate to the API Tokens section, then copy the WorkspaceId value.
• {DEFAULT_USER_ROLE}: The default SAP LeanIX role to be assigned to the user. Possible values:
  • VIEWER
  • MEMBER
  • ADMIN

Example request:

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens \
  --header 'Authorization: Bearer {SHORT_LIVED_ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{"description":"My first long-lived bearer token","scope":"","scimConfiguration":{"workspaceId":"{WORKSPACE_ID}","permissionRole":"{DEFAULT_USER_ROLE}"}}'

A long-lived access token is returned in the accessToken attribute in the response.

🚧

Caution

The access token is shown only once in the response. Save the token and make sure that you store it securely.

Example response:

{
    "id": "47394a58-4165-45e4-6ge4-f9a706dad4fb",
    "accountId": "fb526496-751b-44cd-31h3-369f233fa543",
    "accessTokenId": "b25f9c17-5fab-41a5-96a5-fef3bc1943e1",
    "valid": true,
    "accessToken": "eyJraWQiOiI0MDJjODg3NTBjZmJhOGQzZTQ0Nj...LlRK-8-W7cg",
    "creatorId": "8c263138-afab-4823-34gh-3e32628d4dc6",
    "description": "My first long-lived bearer token",
    "createdAt": "2024-04-19T12:45:23.461Z"
}

Retrieving Long-Lived Access Tokens

Before proceeding, obtain a short-lived access token. The associated Technical User must have the ACCOUNTADMIN role. For instructions, see Obtaining a Short-Lived Access Token.

To retrieve existing long-lived access tokens, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens

Replace {SUBDOMAIN} and {SHORT_LIVED_ACCESS_TOKEN} with your values.

Example request:

curl --request GET \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens \
  --header 'Authorization: Bearer {SHORT_LIVED_ACCESS_TOKEN}'

Example response:

[
  {
    "id": "47394a58-4165-45e4-6ge4-f9a706dad4fb",
    "accountId": "fb526496-751b-44cd-31h3-369f233fa543",
    "accessTokenId": "b25f9c17-5fab-41a5-96a5-fef3bc1943e1",
    "valid": true,
    "creatorId": "8c263138-afab-4823-34gh-3e32628d4dc6",
    "description": "My first long-lived bearer token",
    "createdAt": "2024-04-19T12:45:23.461Z"
  },
  ...
]

Deactivating a Long-Lived Access Token

Before proceeding, do the following:

• Obtain a short-lived access token. The associated Technical User must have the ACCOUNTADMIN role. For instructions, see Obtaining a Short-Lived Access Token.
• Get the id of the token that you want to deactivate. To do that, retrieve all long-lived access tokens and copy the token id from the response. For instructions, see Retrieving Long-Lived Access Tokens.

To deactivate a long-lived access token, make a POST request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens/{id}/invalidate

Replace {SUBDOMAIN} and {SHORT_LIVED_ACCESS_TOKEN} with your values.

Example request:

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens/47394a58-4165-45e4-6ge4-f9a706dad4fb/invalidate \
  --header 'Authorization: Bearer {SHORT_LIVED_ACCESS_TOKEN}'

Example response:

{
  "id": "47394a58-4165-45e4-6ge4-f9a706dad4fb",
  "accountId": "fb526496-751b-44cd-31h3-369f233fa543",
  "accessTokenId": "b25f9c17-5fab-41a5-96a5-fef3bc1943e1",
  "valid": false,
  "creatorId": "8c263138-afab-4823-34gh-3e32628d4dc6",
  "description": "My first long-lived bearer token",
  "createdAt": "2024-04-19T12:45:23.461Z"
}

The valid attribute returned in the response is set to false, which means that the token is deactivated and can no longer be used to perform any authenticated operations.