Registering your OAuth client in the Celonis Platform

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

For an overview of the differences between OAuth 2.0 and using Application or API Keys, see: Using OAuth 2.0.

Registering your OAuth client

To register your OAuth clients in Celonis Platform:

Go to Admin & Settings > Applications.
The interface shows all applications and their type split into two categories: customer-configured and Celonis-configured applications. Customer-configured applications are managed by customer admins and are created when, for example, the admin needs to integrate another application with the team. Celonis-configured applications are configured and managed by Celonis services to integrate seamlessly with the team. For example: Task Mining creates an OAuth client every time a device is activated. The On-Premise Client is used to bootstrap extraction whenever it is installed on an on-prem device.
Click Add new application and select OAuth Client.
Configure the OAuth client with the following fields:
- Name: An internal reference to this client.
- Grant type:
  - Client credentials (default) - best used for server-to-server or machine-to-machine communication without user involvement. When using this grant type, client sends its client_id and client_secret to an authorization server to receive an access token. This token is then used to make requests to a protected API on behalf of the application itself, not a user.
  - Authorization code - this authentication flow includes user involvement. In this gran type, the client application operated by a user exchanges the authorization code for an access token.
- Authentication methods
  - Client secret basic: With this method, the client uses the Authorization header to send the client_id and client_secret in the following format: Authorization: Basic encoded_credentials.
    Here the value of encoded_credentials corresponds to the base64 encoding of OAuth client’s client_id:client_secret.
  - Client secret post: The client authenticates itself by providing the client_id and client_secret in the HTTP request body as a form parameter.
Click Define scopes.
Scopes allow you to define areas to which the client should have access within its current permissions. You can't grant additional permissions to a client using scopes.
Select resource types within Celonis Platform to which the clients will have access based on granted permissions. Chosen scopes give the client access to specific Celonis Platform APIs.
Click Create.

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. Every scope should have a name and a description, which unambiguously explains which APIs can be accessed with the scope based on the permissions granted to the client.

You can view all applications in your Celonis Platform instance under Admin & Settings > Applications. Note that the "Created by" column in that overview shows data only for newly created apps with OAuth clients.

Assigning permission to your OAuth application

In your Celonis Platform, go to Admin & Settings > Permissions.
Locate the service you need and click Edit.
In this example, we’re updating the User Provisioning service.
Select the required template for your application and, if required, enable SCIM permissions.
In this example, we are granting our application with manage permissions and enabling SCIM permissions.
Click Save.
Add the access token to the authorization header of your requests using the following format:
```
Authorization: Bearer ACCESS_TOKEN
```

Your application now has the correct permissions within your Celonis Platform.

Regenerating OAuth client secrets

For security reasons, you may want to regenerate the client secret using the following steps:

In your Celonis Platform instance, go to Admin & Settings > Applications.
Find your OAuth client and click the three-dot menu next to it.
Select Regenerate secret.

Once you generate a new client secret, make sure to update the secret in all integrations that use that client.

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, go to Edit Profile and then to the section OAuth Client Management. From there you can view which applications (OAuth clients) have been granted consent and revoke that consent.

Requesting OAuth access tokens

After registering your OAuth client and assigning it the necessary permissions in your Celonis Platform team, you can now use a REST API client such as Postman to make a POST request for your access token.

To do this, you need your token URL:

https://<team>.<cluster>.celonis.cloud/oauth2/token

And in Postman:

After registering your OAuth client and assigning it the necessary permissions in your Celonis Platform team, you can use a REST API client such as Postman to make a POST request for your access token.

You then need to append at least two query parameters to your token URL:

Grant type: This must be "client_credentials" as this is currently the supported grant type for OAuth clients.
Scope: This should be the Celonis Platform services that you have granted permissions to (based on the service string). In our example, we've included Studio:

https://<team>.<cluster>.celonis.cloud/oauth2/token?grant_type=client_credentials&scope=studio

And in Postman:

After you append two query parameters to your token URL, they appear like this in Postman.

You can then configure the Authorization. In this example, we're using a basic authentication using a username (the client ID) and password (the client secret):

Configure the Authorization. In this example, we're using basic authentication with a username (the client ID) and password (the client secret).

This configuration gives you an OAuth request such as:

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>

And running the request returns a response that includes your access token:

{
	"access_token": "randomizedAcessToken",
	"scope": "scope1 scope2 scopeN",
	"token_type": "Bearer",
	"expires_in": 899
}

This access token can then be used with a bearer token authentication method to request access to and information from the Celonis Platform services you need:

The bearer token. Use this with the access token to request access to the Celonis Platform services you need.

OAuth scopes

Scopes allow you to define areas to which the client should have access within its current permissions.

You must define scopes for every new OAuth application you add to Celonis Platform. To learn how to create a new application, see Registering your OAuth client in the Celonis Platform.

Here's a list of available scopes:

Scope group	Scope	Description	Additional details
Action engine	action-engine.projects	Gives access to projects based on granted permissions.	Gives access to Action Engine resources via the content-cli to Push and pull action-engine skills
Audit	audit.log:read	Gives read-only access audit logs based on granted permissions.	Gives read-only access to the Audit Log API. Can be used to export Audit Log events back into a Celonis Studio view or other tool for analysis or risk assessment needs.
Authorization	authorization.permissions:read	Gives access to read permissions based on granted permissions.
Integration	integration.data-models:read	Gives read-only access to data models based on granted permissions.
	integration.data-pools	Gives access to data pools based on granted permissions.	Gives access to integration resources using the following APIs: content-cli Push and pull data-pools and connections Import and export data pools Update data-pools, data-pool connections PyCelonis Manage data-pools and associated entities: connections, data models, variables, tables, jobs Push data into data-pools Export data from data models Data Push API The Data Push API provides an easy way to transfer data into Celonis. Continuous Data Push API Process Data Model API The process data model API allows you to completely or partially reload your data models, ensuring that the latest data from your source system is available.
	integration.data-pools:continuous_data_push	Gives access to continuously push data to data pools based on granted permissions.	Gives access to the Continuous Data Push API.
	integration.data-pools:data_push	Gives access to push data to data pools based on granted permissions.	Gives access to the Data Push API.
	integration.data-pools:query	Gives access to querying Data Pools based on granted permissions.
	integration.data-pools:read	Gives read-only access to data pools based on granted permissions.
Intelligence API	intelligence.conversations:write	Gives access to the Studio Process Copilot conversational API based on the granted permissions.	Gives access to the Chat API. This is an API to interact with a Process Copilot built in Celonis (as described here). Can also be used to provide access to the Process Copilot Asset from both Action Flows and Orchestration Engine.
	intelligence.knowledge-models:read	Gives read-only access to knowledge models and their data, filters, records, KPIs, OData metadata, specs, and triggers based on granted permissions.	Gives you access to Knowledge Model API - Query knowledge-model data and metadata.
	intelligence.subscriptions:manage	Allows managing subscriptions to knowledge-model triggers, including creation, updates, and event replay, based on granted permissions.	Event Subscription API - discover business triggers, subscribe to them, manage event subscriptions and emit spontaneous events.
Machine Learning	machine-learning	Gives access to the Machine Learning Workbench API based on the granted permissions.	Gives access to the Machine Learning Workbench API.
MCP	mcp-asset.tools:execute	Allows executing MCP Server Asset Tools, based on granted permissions.
On-prem clients	on-prem-client	Gives access to on-premise client based on granted permissions.
Orchestration Engine	orchestration-engine	Gives access to Process Orchestration and Forms based on granted permissions.
Package manager	package-manager	Gives access to package manager based on granted permissions.
Platform adoption	platform-adoption.tracking-events:read	Gives read-only access to platform-adoption tracking-events based on granted permissions.	Gives read-only access to the Platform Adoption API - to export user access data for Studio and Apps in order to better understand usage and adoption of packages and views.
Storage manager	storage-manager.buckets	Gives access to storage-manager buckets based on granted permissions.	Gives access to the SFTP Storage Manager API.
Studio	knowledge-models.augmented-attributes:update	Gives access to update Augmented Attributes data based on granted permissions.	Gives access to the Studio resources via the following APIs: content-cli Push and pull data-pools and connections Import and export data pools Update data-pools, data-pool connections PyCelonis Manage data-pools and associated entities: connections, data models, variables, tables, jobs Push data into data-pools Export data from data models Data Push API The Data Push API provides an easy way to transfer data into Celonis. Continuous Data Push API Process Data Model API The process data model API allows you to completely or partially reload your data models, ensuring that the latest data from your source system is available.
	knowledge-models:query	Gives access to running queries on a Knowledge Model based on granted permissions.
	knowledge-models:read	Gives read-only access to Knowledge Models based on granted permissions.
	skills:execute	Gives access to executing Skills based on granted permissions.
	skills:read	Gives access to reading Skills data based on granted permissions.
	studio	Gives access to studio based on granted permissions.
	studio.packages:read	Gives read-only access to studio packages based on granted permissions.
	tasks:read	Gives access to reading Tasks data based on granted permissions.
	tasks:update	Gives access to updating Tasks data based on granted permissions.
	triggers:manage	Gives access to managing trigger subscriptions to data changes based on granted permissions.
	triggers:read	Gives read-only access to triggers based on granted permissions.
Task Mining	task-mining.clients:suspend	Allows suspending the data capturing of Task Mining clients.
	task-mining.gateway	Gives access to Task Mining Gateway integration API.
	task-mining.metadata:read	Gives read-only access to Task Mining user metadata.
Team	team.user-group-info:read	Gives read-only access to team user and group information based on granted permissions.	Gives read-only access to the User Group Info API to export data that returns all user and group details within a team to better understand users, the roles they have and the groups they are part of.
Team	team.login-history:read	Gives read-only access to team login history based on granted permissions.	Gives read-only access to the Team Login History API to export user login data for the whole team in order to better understand who accesses the team the most or least.
User provisioning	user-provisioning.scim	Gives access to the SCIM API based on granted permissions.	Gives access to the SCIM API to automate the provisioning of Users, Groups and Roles with the active directory.