🚧

Warning

Personal API Tokens are deprecated. Please use the Technical User functionality to create an API Token.

Overview

LeanIX employs OAuth2 for user authentication across all available APIs. The flow outlined below demonstrates how an API Token is used to obtain an Access Token. Administrators can generate one or more API Tokens via the LeanIX Administration interface, each tied to a separate Technical User and possessing an expiration date. For instructions on creating an API Token, refer to the Technical User section.

The base_url can be either:

• https://app.leanix.net - If you are using the default instance of LeanIX
• https://<customer>.leanix.net - If your have a dedicated instance of LeanIX

Example Request

Use the following code to request an Access Token. Here are a few examples in Shell, Javascript and Java.

curl --request POST \
  --url https://app.leanix.net/services/mtm/v1/oauth2/token \
  -u apitoken:JqcSfeB7sO3Bd9dEDcSOXfjs6G6ORCsT6G9fBHCc \
  --data grant_type=client_credentials

var apiToken = "vsugx4Stp4FLAmZOZ4GECv5XjESMNSs5am8Rd4RA";
var instance = "https://app.leanix.net";
var auth = btoa("apitoken:" +  apiToken);
var settings = {
  "async": true,
  "url": instance + "/services/mtm/v1/oauth2/token",
  "method": "POST",
  "headers": {
    "authorization": "Basic " + auth,
  },
  "data": {
    "grant_type": "client_credentials"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=client_credentials");
Request request = new Request.Builder()
  .url("https://app.leanix.net/services/mtm/v1/oauth2/token")
  .post(body)
  .addHeader("authorization", "Basic YXBpdG9rZW46SnFjU2ZlQjdzTzNCZDlkRURjU09YZmpzNkc2T1JDc1Q2RzlmQkhDYw==")
  .build();

Response response = client.newCall(request).execute();

The Access Token has a specific structure, with the token itself located in the access_token field (shortened for the example below). This value should be included in subsequent requests as a Bearer token. Note that the Access Token is time-sensitive: its validity period, in seconds, is specified in the expires_in field. A new token must be requested before the current one expires. If you are using our SDKs, this renewal process is handled automatically.

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

The access_token can now be included as a Bearer token in requests to any LeanIX API. For example, to retrieve a list of Applications (internally referred to as 'services') from the 'demo' workspace's IT Inventory, you would use the access_token in this manner.

curl --request GET \
  --url https://app.leanix.net/test/api/v1/services \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA'

var settings = {
  "url": "https://app.leanix.net/demo/api/v1/services",
  "method": "GET",
  "headers": {
    "authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://app.leanix.net/test/api/v1/services")
  .get()
  .addHeader("authorization", "Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA")
  .build();

Response response = client.newCall(request).execute();

Debug an Access Token

Once authenticated via the token endpoint, you will receive an Access Token in JWT format. These JWT tokens are signed with a Private Key, enabling our APIs to validate their authenticity. You may use the debugger at JWT.IO to decode an Access Token and view details such as permissions or expiration dates.

Tutorial: OAuth 2.0 authentication for REST APIs

See https://blogs.sap.com/2017/01/23/oauth-2.0-authentication-within-a-udf-mapping-to-be-included-in-rest-receiver-channel/ for a great tutorial how to implement OAuth 2.0 authentication for a REST API like offered by LeanIX.