# Migrating to OAuth 2.0

OAuth 2.0 is an industry-standard framework that allows different applications to securely interact with each other on behalf of users without sharing sensitive credentials. More about OAuth [here](https://docs.celonis.com/en/using-oauth-2-0.html).

At Celonis, we are in the process of moving away from long term API and Application keys and rapidly moving towards OAuth. This section highlights what Celonis APIs today already support OAuth and how you can migrate your applications that call these APIs using API/Application keys to OAuth.

## Celonis APIs that currently support OAuth 2.0:

| API Name | OAuth Scope |
|  --- | --- |
| [Audit Log API](https://developer.celonis.com/celonis-apis/audit-log-api/overview/) | audit.log:read |
| [Platform Adoption API](https://developer.celonis.com/celonis-apis/platform-api/overview/) | platform-adoption.tracking-events:read |
| [Team Login History API](https://developer.celonis.com/celonis-apis/team-api/overview/) | team.login-history:read |
| [Team Members API](https://developer.celonis.com/celonis-apis/team-api/overview/) | team.user-group-info:read |
| [Machine Learning Workbench API](https://developer.celonis.com/mlwb/overview/) | machine-learning |
| [Process Intelligence APIs](https://developer.celonis.com/process-intelligence-apis/overview/) (Knowledge Model API, EventSubscription API, Chat API) | intelligence.conversations:write, intelligence.conversations:write, intelligence.subscriptions:manage |
| [Standard Data Ingestion API](https://developer.celonis.com/data-ingestion-api/standard/standard_overview/) | integration.data-pools, integration.data-pools:data-push, integration.data-pools:continuous-data-push |
| [Data Job Execution API](https://developer.celonis.com/celonis-apis/data-job-execution-api/) | integration.data-pools |
| [Process Data Model API](/celonis-apis/process-data-model-api) | integration.data-pools |
| [SCIM API](https://developer.celonis.com/celonis-apis/scim-api/overview/) | user-provisioning.scim |
| **Important Update:** SCIM API is now supported with Microsoft EntraID and OAuth.  |


OAuth scopes restrict which APIs are accessible by OAuth clients, while Permissions give access to the individual resources offered by these APIs. For a detailed explanation of what access you get with each OAuth scope listed in the table above, refer to [Registering your OAuth Client](https://docs.celonis.com/en/registering-oauth-client.html#UUID-0a0e0984-8a17-1d4e-175c-aa47448f9e66_section-idm234408737198615).

## Migrating applications calling Celonis APIs to OAuth 2.0 from API/Application keys

If you have any application in your Celonis environment using any of the above APIs, then we strongly recommend that you migrate your applications to OAuth 2.0 and move away from long term API/Application keys as Celonis is moving away from these long term keys in the future.

Given below is an example of how you can migrate to OAuth. In this example, we have used Audit log API, Team Login history API, Platform adoption API, and Member / User Group Info API to show you how you can migrate an application that was previously calling these APIs using an application key to now calling the same APIs using OAuth 2.0.

## Connecting audit log, login history, members, and Studio adoption APIs to Celonis Platform using OAuth 2.0

Within Admin & Settings you can view your audit log, team login history, and studio adoption statistics. However, these views are limited with standardized user interfaces. To run a more in-depth analysis of this data, you can connect to their respective APIs and then use a data extractor to feed this information back into the Celonis Platform. This then lets you create your own views in Studio.

To connect to the APIs and create an extractor, refer to the [Connecting audit log, login history, and Studio adoption APIs to Celonis Platform](/celonis-apis/connecting-to-celonis-platform) topic.

## Testing OAuth credentials

There are multiple ways to test Oauth credentials in Celonis:

### Testing OAuth using Postman or command line

The created OAuth credentials can be best tested in Postman or via the command line tool curl (it is installed in most workstations or can be found in the machine learning workbench in Celonis).

Follow the steps outlined in [Requesting OAuth access tokens](https://docs.celonis.com/en/registering-oauth-client.html#UUID-0a0e0984-8a17-1d4e-175c-aa47448f9e66_UUID-3c4c385a-5026-4307-2787-fafcdb228353) while using the required scopes.

When the credentials are set up correctly you should receive a scope similiar to:


```
    {
        "access_token": "randomizedAccessToken",
        "scope": "scope 1 scope 2 scopeN",
        "token_type": "Bearer",
        "expires_in": 899
    }
```

### Testing OAuth using Swagger UI

You can now test your APIs with Swagger UI. To do this, you need your team name and environment cluster and your OAuth client from the earlier procedure. You can find your team name and environment cluster from any URL, for example from the **Permissions** page from the procedure above.


```
https://[teamname].[realm].celonis.cloud/ui/team/permissions
```

With your team name and environment cluster, you can then access the Swagger UI using this URL:


```
https://[teamname].[realm].celonis.cloud/swagger-ui/index.html?configUrl=/log/v3/api-docs/swagger-config
```

Once on the Swagger UI, follow these steps to test your API:

1. Click **Authorize**. ![](/assets/celonis-audit-log-api.2212da9cd15c5d59918a8fe742ce2eb21ac1ba75761ac579b186b891aff6b2f7.1df0a4ac.png)
2. When using an OAuth client (Recommended), enter "Bearer" followed by a space and then copy the client ID you obtained for the client. For example: `Bearer XxxxxxAxxxxBxxxxCxxxXBBBBX`
3. Click **Authorize**. Once the authorization is successful, click **Close** .
4. Expand the GET call for the API you want to test and click **Try it out**.
5. Click **Execute**. ![Screenshot showing the location of the Execute button.](/assets/celonis-api-execute-button.7e8a6593dd629912c77911b1560a84aa59ba5c1f99a652c9ade36e3bf7c62343.1df0a4ac.png)


You will now see the response from the API, including the header that shows the Token and the URL.

## Migrating your application to OAuth from Application/API key

Go to the Data Pool where your Data Connection to the Celonis API lies and click on the menu of the data connection.

1. Go to **Authorization**, add additional authentication and select "OAuth2".
2. Select “Client Credentials” as the **Grant type**.
3. Add an additional **Request Body** parameter with the key “scope” and the value for the scopes relevant for the Celonis APIs (separated by blank space, example shows the scope `audit.log:read`)


Important
The "scope" parameter must be added for OAuth. This parameter must be added in the "Additional request parameter" section, **NOT** in the "Additional Request Header" field.

1. Get bearer Token with the Endpoint to /oauth2/token.![](/assets/celonis-api-authentication.25c0f515729429cb948d5829bb0cf0a20fb7fd2365662e445a283281003c4d36.1df0a4ac.png)


Go to **Data Connection Test**:

1. Enter the Client ID and Client Secret.
2. Select the End point that you have also chosen for AppKey "authentication3".
  1. **Define Endpoints:** Configure a new endpoint and enter an endpoint name.
  2. **Endpoint Configure Request:** In URL enter {Connection.API_URL}/ [Enter what is shown in the Swagger doc URL after celonis.com.cloud]. So the final text could read:

```
`{Connection.API_URL}/log/api/external/audit?Request parameters and Headers can be completed after as needed).{Connection.API_URL}/log/api/external/audit?`
```
3. Click **Save**.
4. Click **Build Response**.
5. Click **Test Connection**. ![](/assets/celonis-api-data_connection.ae83f74e0a481ed846a3fdd723c636bb470ce279dddf10362ae98fdccf5a4040.1df0a4ac.png)
6. Click **Finish**.
7. See the [Troubleshooting](#troubleshooting) section below to resolve any errors.


When the connection test was successful, save the connection. To run the extraction test, go to the data job and manually execute an extraction (e.g., delta extraction).

When the extraction was successful, you can go back to the customization of the extractor builder and delete API Key Authentication.
![Authentication menu expanded to show the delete option.](/assets/celonis-api-delete-authentication-key.ecb8cd44594d28dc80bfdb67577b0e2010ef797aad9cd42359f9c1082d42fdc0.1df0a4ac.png)

## Troubleshooting

The most common errors during authentication and how to fix them.

* Wrong / missing scope
  * Postman ![](/assets/celonis-api-troubleshooting-wrong-scope.d9c9ddc6ab101036bfa94d5714042719e3557354c1fd05be0befc2390ebab435.1df0a4ac.png)
  * Extractor Builder ![](/assets/celonis-api-troubleshooting-test-failed.883e933df7f505f1e174b73c09d833c67e218a04f5f831aa41480e6bb1008c31.1df0a4ac.png)
* Missing permission / 401 unauthorized
  * Postman ![](/assets/celonis-api-troubleshooting-unauthorized.a6c71b1362dde93d81bbec9b6ac5068221d95bd7bc62716bf038107a023b1bde.1df0a4ac.png)
  * Extractor Builder ![](/assets/celonis-api-troubleshooting-test-failed2.32ac26a5b0ab2973e13df4e06032e034f5f02dc3b39977a52550675050411082.1df0a4ac.png)
* Incorrect client ID / secret
  * Postman ![](/assets/celonis-api-troubleshooting-invalid-client.ca93a2cb413f75e9bcea670f0c6e6f41c44298a2ef5b347335164ca8b40673da.1df0a4ac.png)
  * Extractor Builder ![](/assets/celonis-api-troubleshooting-test-failed3.7d472aa912896841ddaff37306e7c337fb0cf9091bf5236d6ac46d67c79b1c4b.1df0a4ac.png)
* To send as params / request body
  * While creating Application based on the choice ![](/assets/celonis-api-troubleshooting-grant-type.aab5b0d7ef603a1f514f1285accf4e680ceb2b12e51ada53ed9785c9cfd85ea2.1df0a4ac.png)
  * Postman
    * If Client basic, send as request params ![](/assets/celonis-api-troubleshooting-request-params.205fa02be594ae3ed619bc57fed890f0c78da93eaad2941f4117243089a4f451.1df0a4ac.png)
    * If Client Post, send as request body ![](/assets/celonis-api-troubleshooting-request-body.f035d121e39236822148255cf094567842309977a9198730221a0a7630ca16f1.1df0a4ac.png)


## Additional info on creating an extractor and an extraction for API endpoints

If you are not familiar with how to create an extractor for Celonis APIs or how to create an extraction, refer to the sections below.

### Creating an extractor builder for APIs

After testing your APIs, you now need to create an extractor. This extractor pulls detailed information from your team (via the API), allowing you to add this to your Studio views.

The extractor you create in the following steps is without both pagination and headers:

1. From your team, click **Data - Data Integration**.
2. Click **New Data Pool > Create from scratch**, add a name, and then click **Save**.
3. From the data integration diagram, click **Connect to Data Source** and then select **Connect to Data Source**. ![](/assets/connect-to-data-source.45c8cef34786e6e162ee708466bdcf1be25c00b5d6644edf143abc2e608c977b.1df0a4ac.png)
4. Click **Custom** and then click the plus icon. Here you have three options:
  * Build a new Extractor ![](/assets/build-new-extractor.773de1f5c7cc25c0e394abad00eb7c02342507aa82feb4c905ee60648ede5bdd.1df0a4ac.png)
  * Customize a Celonis extractor
  * Import from File (For Audit logs with pagination, use this [JSON template](https://docs.celonis.com/downloads/audit%20log%20api%20extractor%20template_export.json), this template can also act as the foundation for the Login Log API and the Adoption API).
5. When building a new extractor using the four stage wizard, enter the following information:
  * **Extractor name:** This can be custom to your extractor.
  * **Connection Parameters - Edit API URL:** Enter your Celonis team URL in the following format - https:// [Your Team].celonis.cloud


### Creating an extraction

Once your extractor is built, you can configure delta loads by following these steps:

1. Click **Add Extraction**.
2. Click on the **Parameters** tab.
3. Click **New Parameters** and populate and save the parameters as follows:
  * **Placeholder:** LastUpdated
  * **Name:** Last Updated
  * **Type:** Dynamic
  * **Table:** AuthenticationEvents
  * **Column:** timestamp
  * **Default value:** 01/01/2000, 00:00:00
4. Click on the **Tab** configuration tab, scroll to **Delta Filter Statement** and add the following: `= from = < %=LastUpdated%>`
5. Now add a data model, a data model load and a schedule following the user interface.