Skip to main content

Registering your OAuth client

Registering an OAuth client establishes secure, token-based programmatic authentication for external applications connecting to the Celonis Platform. This workflow replaces static API keys with dynamic client credentials to safeguard automated pipelines, such as continuous data ingestion logs within your Accounts Payable or Order-to-Cash processes.

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

 

Before you begin

  • Verify that your user account has Admin permissions within your Celonis Platform team.

  • Confirm that your external application supports standard OAuth 2.0 client credentials or authorization code flows.

Registering your OAuth client

To register your OAuth clients:

  1. Go to Admin & Settings > Applications.

    Screenshot of the Applications screen in the Admin and Settings module.

  2. Review the active applications directory to identify existing connections:

    • Customer-configured: Custom integrations managed by your team administrators.

    • Celonis-configued: Automated system capabilities (such as Task Mining or On-Premise clients) managed automatically by the platform.

  3. Click Add new application and select OAuth Client.

    Screenshot showing the Add New Application menu with the OAuth Client option highlighted.

  4. Configure the client fields using these operational parameters:

    • Name: Enter a unique identifier (for example, `O2C_Data_Push_Client` to isolate Order-to-Cash extraction logs).

    • Grant type: Select Client credentials for headless server-to-server pipelines, or Authorization code for user-interactive applications.

    • Authentication methods:

      • Client secret basic: Transmits authentication credentials via the standard HTTP Authorization header using the format: Authorization: Basic encoded_credentials.

        The value of encoded_credentials corresponds to the base64 encoding of the OAuth client’s client_id:client_secret configuration string.

      • Client secret post: Authenticates the client by passing the client_id and client_secret parameters within the HTTP request body as form data.

  5. Click Define scopes and select your target resource boundaries (for example, assign `packages:read` to extract continuous data ingestion logs without exposing tenant modification capabilities).

  6. Select the target resource types to map API accessibility boundaries (for example, assign packages:read to extract continuous data ingestion logs without exposing core tenant modification settings).

  7. Click Create.

  8. Copy the generated Client ID and Client Secret immediately upon creation. Celonis displays these credentials only once.

Assigning permission to your OAuth application

  1. Go to Admin & Settings > Permissions.

  2. Locate your targeted integration service and click Edit (for example, select the AP_Vendor_Provisioning_Service to update transactional access parameters).

    A screenshot showing where the edit button is located within the permissions area.

  3. Select the required template for your application and enable SCIM permissions if your workflow requires user synchronization.

    Enable manage permissions and select SCIM permissions to authorize programmatic automated identity synchronization.

  4. Click Save.

  5. Append the generated access token to the authorization header of your programmatic API requests using the following format:

    Authorization: Bearer ACCESS_TOKEN

The target application holds active, verified functional permissions within your environment.

Regenerating OAuth client secrets

Regenerate the client secret regularly to maintain credential rotation security across your external pipelines.

  1. Go to Admin & Settings > Applications.

  2. Find your OAuth client and click the three-dot menu next to it.

  3. Select Regenerate secret.

    Screenshot of the options menu on the Applications screen with the Regenerate Secret option highlighted.

Update the newly generated client secret across all connected third-party integration scripts to prevent credential failure.

Managing OAuth client consent

Users authorize OAuth clients to access specific platform resources on their behalf during authentication flows. Review active application authorizations regularly to audit access permissions and secure user session data.

To view or revoke application access:

  1. Click your profile avatar and select Edit Profile.

  2. Navigate to the OAuth Client Management section.

  3. Review the directory of applications that hold active consent.

  4. Click Revoke Consent next to any application to immediately terminate its programmatic access to your Celonis resources.

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.

Related topics