Getting Started

This page describes how to get started with the Intelligence API in a simple way using Postman.

Prerequisites

  1. You need to have a team in Celonis Platform.
  2. You need to have a Knowledge Model available in your team.
  3. You must request the activation of the API in your Celonis Platform Team to the account team.

Before starting

Determine the URL for your team

First you need to determine what is the URL for your team and cluster.

  • The base URL for the Celonis API is https://<team>.<cluster>.celonis.cloud/intelligence/api

To find the team and the cluster, please check the URL you use to access the Celonis Platform and retrieve the team and cluster from it.

For example, the base URL for dev team in US-2 cluster would be:
https://dev.us-2.celonis.cloud/intelligence/api

Install a REST client

Since the Intelligence API is a REST API, you will need to have a way to interact with it. There are multiple ways to do this, but to make things simple, we will use Postman, which is a very popular free REST client.

If you already have a REST client, you can ignore this section.

Otherwise, go to the Postman Download page and download it for your Operating System. Once it's downloaded, install it.

Once installed, it should look like something like this:

Postman

To start using it, create an account or click on "Skip and go to the app".

Authentication

Each request to the API must be authenticated with a Celonis Platform API key. There are two ways of doing this:

Using a User API key.

You can find out how to create an user API key by following our User API Keys guide.

The Celonis API uses Bearer Token Authentication for verifying consumer access. The credentials must be sent in an Authorization header in the HTTP request. Credentials sent in the URL or body of the request will be ignored.

To authenticate using Bearer Token Authentication:

  1. Create the token in the Celonis Platform:
    MDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM
  2. Include the string in the HTTP Authorization header formatted like this:
    Authorization: Bearer MDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM

Using an Application API key (user independent one).

You can find out how to create an AppKey by following our Application API Keys guide.

To authenticate using AppKey Authentication:

  1. Create the AppKey in the Celonis Platform:
    MzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr
  2. Include the string in the HTTP Authorization header formatted like this:
    Authorization: AppKey MzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr

IMPORTANT: For production solutions, we strongly recommend using Application keys instead of User API keys. User API keys should be used for testing purposes only.

Using an OAuth token

To generate tokes using OAuth, it is necessary to follow some configuration steps, described below.

How to Register OAuth client in Celonis Platform

OAuth can be used as an authentication method for Celonis Platform, which offers a more secure and flexible way of granting permissions to clients (applications) compared to API keys.

OAuth client Authentication Methods

Client secret basic: with this method, the client sends the clientid and clientsecret using the Authorization header, in the following format:

  • Authorization: Basic encoded_credentials.

Here the value of encodedcredentials corresponds to the base64 encoding of OAuth client’s **clientid:client_secret**.

Client secret post: the client authentications itself by providing the client_id and client_secret in the HTTP request body as a form parameter. To ask for multiples scopes each scope should be separated by space

Registering a OAuth client in Celonis Platform
  1. In the Celonis Platform instance, go to Admin & Setting admin and setting
  2. After In Application Application
  3. Then in the upper-right corner, click Add new application and select OAuth Client. +Add new application

New OAuth Client

  1. Give a meaningful name.
  2. The OAuth grant type supported is “Client Credentials”.Select of the following authentication methods: Client secret basic or Client secret post
  3. Then click in Define scopes - Scopes do not grant any additional permissions beyond what the client has. They specify the access-level that the client needs. Select what levels within Celonis Platform the clients will have access to based on granted permissions. Every scope has a name and a description, describing what can be accessed with the scope based on the permissions granted to the client
  4. Finally click in Create.
  5. As scopes only allow access to the APIs, the created OAuth client should now be assigned permissions to resources behind those APIs
After creating a client in Celonis Platform, developers receive client credentials: client ID and client secret. The client secret needs to be copied as it cannot be accessed anymore subsequently.
OAuth Endpoints
The token endpoint is available at https://< team-url >/oauth2/token.

OAuth request

Copy
Copied
curl --request POST \
  --url https://<team>.<cluster>.celonis.cloud/oauth2/token \
  --header 'content-type: multipart/form-data' \
  --form client_id=<client id> \
  --form client_secret=<client secret> \
  --form grant_type=client_credentials \
  --form scope=<scope1 scope2 scopeN>

OAuth token response

Copy
Copied
{
	"access_token": "eyJraWQiOiJkZXZlbG9wLWVzMzg0IiwiYWxnIjoiRVMzODQifQ.eyJhdWQiOlsiYjllMzgwZDYtMmUxZS00MmQ5LWI3YjUtZTJkZDI5MGYxZTU5IiwiYXBpbmF1dHMuZGV2ZWxvcC5jZWxvbmlzLmNsb3VkIl0sIm5iZiI6MTcxMjEzNDU4NywiYXpwIjoiYjllMzgwZDYtMmUxZS00MmQ5LWI3YjUtZTJkZDI5MGYxZTU5Iiwic2NvcGUiOlsib3BlbmlkIl0sImlzcyI6Imh0dHBzOi8vYXBpbmF1dHMuZGV2ZWxvcC5jZWxvbmlzLmNsb3VkIiwiZXhwIjoxNzEyMTM1NDg3LCJpYXQiOjE3MTIxMzQ1ODcsImp0aSI6IjI2ZjlhNTU3LWQwMTEtNDcyNy05MTNhLWU3NmU3MDIzMTkyMyJ9.XIBj89ymumPaDL_InAsuWiL_6e5GeMpDGgPz3cZNWF3rNzNTc4GRAXMrtBjU9Gg6SWpyqPK0tTaTsrf88fmc0MboYXvKH0CxtpqWlDp0h_QSRMb1ZsCD226kv83xbh86",
	"scope": "scope1 scope2 scopeN",
	"token_type": "Bearer",
	"expires_in": 899
}

Regenerating OAuth client secrets

For security reasons, you may want to regenerate the client secret. For this, navigate to Admin & Setting > Applications and find the OAuth client. Click on the three dots three dots menu on the right and choose Regenerate Secret. After getting the new secret, make sure to update it in any integration this client is used in.

Managing OAuth Client Consent

During OAuth authorization flows, users can give consent to OAuth clients to access resources on their behalf. To view which OAuth clients have been granted consent, navigate to Edit Profile and then to the section OAuth Client Management. There, you can view which applications (OAuth clients) have been granted consent and you can revoke such a consent by clicking on Edit and then Revoke Consent for the corresponding client.

OAuth Scopes used in Intelligence API

  • OAuth Scope:
    • studio

How to use OAuth token

The Celonis API uses Bearer Token Authentication for verifying consumer access. The credentials must be sent in an Authorization header in the HTTP request. Credentials sent in the URL or body of the request will be ignored.

To authenticate using Bearer Token Authentication:

  1. Call the token endpoint ( https://< team-url >/oauth2/token ) to issue a new token.
  2. Include the access token in the HTTP Authorization header formatted like this:
    Authorization: Bearer eyJraWQiOiJkZXZlbG9wLWVzMzg0IiwiYWxnIjoiRVMzODQifQ.eyJhdWQiOlsiYjllMzgwZDYtMmUxZS00MmQ5LWI3YjUtZTJkZDI5MGYxZTU5IiwiYXBpbmF1dHMuZGV2ZWxvcC5jZWxvbmlzLmNsb3VkIl0sIm5iZiI6MTcxMjEzNDU4NywiYXpwIjoiYjllMzgwZDYtMmUxZS00MmQ5LWI3YjUtZTJkZDI5MGYxZTU5Iiwic2NvcGUiOlsib3BlbmlkIl0sImlzcyI6Imh0dHBzOi8vYXBpbmF1dHMuZGV2ZWxvcC5jZWxvbmlzLmNsb3VkIiwiZXhwIjoxNzEyMTM1NDg3LCJpYXQiOjE3MTIxMzQ1ODcsImp0aSI6IjI2ZjlhNTU3LWQwMTEtNDcyNy05MTNhLWU3NmU3MDIzMTkyMyJ9.XIBj89ymumPaDL     InAsuWiL 6e5GeMpDGgPz3cZNWF3rNzNTc4GRAXMrtBjU9Gg6SWpyqPK0tTaTsrf88fmc0MboYXvKH0CxtpqWlDp0h QSRMb1ZsCD226kv83xbh86

Authorization

You must set the right permissions and ensure the User API Key or the Application API Key leveraged for authorization purposes has access to the Celonis Celonis Platform Studio package containing the Knowledge Model(s) you would like to access through Intelligence APIs.

You can grant access permissions by following these steps:

  • Go to the Studio package.
  • Click on the three dots and select Permissions from the pop-up menu.
  • Search for the User (in case you are using a Bearer token ) or AppKey (in case you are using an AppKey ) and grant at least USE PACKAGE rights.

Consuming the Intelligence API

Once we have completed the previous steps, we can start making requests to the API. For that we will use Postman (or any other REST client), which we should already have installed in our system.

  1. Go to File > New... and select HTTP Request. Once you do this, you should see something like this:

Postman empty request

  1. Enter the request URL next to the Send button. For this URL we will use the one we got from the "Determine the URL for your team" section. In our example, the URL was https://dev.us-2.celonis.cloud/intelligence/api .
  2. Now we need to set our API or Application Key in order to authenticate our requests. To do this, click on the "Headers" tab beneath the URL we just entered. In key, type "Authorization" and for value, put:
  3. Bearer <YOUR_KEY> if you have a User API Key
  4. AppKey <YOUR_KEY> if you have a AppKey

In the following example, we have an AppKey:

Postman authentication section

Getting the list of Knowledge Models

Once we have completed the steps above, we should now be able to start getting some data. We will start getting the full list of Knowledge Models that our API token has access to.

First, start appending "/knowledge-models" to the URL we got from previous steps: https://dev.us-2.celonis.cloud/intelligence/api/knowledge-models.

After that, click on the "Send" button next to the URL. You should get something like this:

Knowledge Models response

Inside the content section, you will see a list of all your Knowledge Models. The Knowledge Models will be divided in pages. By default, the page size will be 50. If you happen to have more than 50 Knowledge Models, you can navigate to the following page, adding a "page" query parameter. The pages start at 0, so you can display the second page by setting a page value of 1.

Setting a page query parameter

In our example, this is not needed, as we only have 13 Knowledge Models. However, you might want to specify other query parameters like:

  • pageSize: Sets the size of each page.
  • sort: Sort the results by id or name.

You can check the full list of parameters and possible responses you can get in this page.

You can also check the full list of possible errors you can get in the API, in case you need to troubleshoot any issue.

In this quick guide, we managed to create our first request to Intelligence API. If you would like to do more advanced requests, we recommend you to check the full list of capabilities of our API or take a look at
this other guide that walks you through the rest of schema endpoints.