🚧

Warning

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

Overview

LeanIX uses OAuth2 to authenticate users for using all available APIs. The following flow describes, how an Api Token is used to retrieve an Access Token. Administrators can generate one or more API Tokens in the Administration of LeanIX, which have an expiry data until they can be used. See below how to create API Tokens.

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 the following structure. The token itself is contained in the field access_token (shortened in the example below). This is the value which needs to be used in the following requests included as Bearer. Be aware that the Access Token has only a limited time it is valid: The field expires_in contains the number of seconds until the Access Token is expired. You need to request a new token before it is expired (our SDKs do that automatically for you).

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

Now, the access_token can be used in the Bearer in the request to every LeanIX API, e.g. to retrieve a list of Applications (internal name services) from the IT Inventory of the workspace 'demo':

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();

Generate API Tokens

📘

Information

As the Personal API Tokens are being deprecated, we encourage you to use the Technical User functionality to create an API.

In the Adminstration you can create API Tokens. This functionality is currently limited to Admins only. When you create a new API Token, make sure you keep it in a safe place. You will not be able to retrieve the full API token later on for security reasons.

Debug an Access Token

After you have authenticated with the token-endpoint, you retrieve an Access Token in JWT format. Our JWT tokens are signed with a Private Key, so all our APIs can check if they are valid. You can use the debugger at JWT.IO to decode an Access Token. In the debugger you can then see the permissions or the expiry date of your access tokens.

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.