Each request to Celonis APIs must be authenticated with a registered Celonis Identity. There are multiple ways of authenticating as detailed below.

OAuth 2.0 is a well-established industry standard that makes it easier to integrate customer-managed applications with Celonis. OAuth uses scopes to manage access to resources, which means that the OAuth clients can only access APIs allowed by the scopes they are configured to use.

For example, we can have the scope studio that gives access to Studio or the audit.log:read scope that gives read-only access to audit logs. For an OAuth client to be able to access a certain resource (API), the client must have the OAuth scope and the Celonis permissions to do so. This follows the security principle of least privilege so that an OAuth client only gets the required privilege to perform a certain task and not any additional permissions.

If a third party application is using an API key or Application key (AppKey) to integrate with Celonis, they should migrate to OAuth 2.0 as soon as possible using the process below:

1. Create an OAuth 2.0 client as described in the Registering your OAuth 2.0 client help topic.
2. Give the new OAuth 2.0 client permissions on the same packages as your existing Application Key or existing user.
3. Configure the application to use OAuth 2.0 authentication method instead of the old Application Key authentication and provide the client ID, the client secret (optional depending on the grant type) and the authentication.
4. Refresh and redirect (optional for authorization code grant type) URLs using the endpoints and requests described in the OAuth Endpoints section.

The Celonis APIs formerly allowed the use of either a Bearer Token Authentication or AppKey to verify consumer access. OAuth 2.0 is the recommended solution and both the API Key and AppKey options are no longer being supported. Refer to the section above to migrate from either of these solutions to OAuth 2.0.

This grant type uses the client’s credentials to access protected data from a resource server. This is suitable for machine-to-machine authentication.

The most common grant type, the authorization server returns a single-use authorization code to the client. The client then exchanges the code for an access token.

The authorization endpoint is available at https://<team>.<cluster>.celonis.cloud/oauth2/authorize.

The token endpoint is available at https://<team>.<cluster>.celonis.cloud/oauth2/token.

This endpoint is specified by the consumer.

To generate tokens using OAuth 2.0, it is necessary to follow the configuration steps described below.

OAuth token generation request (client_credentials)

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 generation request (authorization_code)

Initiating the Authorization Code flow is a two-step process:

• Step 1: Request Authorization Code. A GET request to the authorize endpoint to receive an authorization code.

  curl --request GET \
  --url 'https://<team>.<cluster>.celonis.cloud/oauth2/authorize?response_type=code&client_id=<client id>&scope=<scope1 scope2 scopeN>&redirect_uri=<redirect uri>&state=<state string>'

• Step 2: Exchange Code for Access Token. Exchange the authorization code received in Step 1 for an access token.

  curl --request POST \
      --url https://<team>.<cluster>.celonis.cloud/oauth2/token \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data-urlencode 'grant_type=authorization_code' \
      --data-urlencode 'code=<authorization code from step 1>' \
      --data-urlencode 'redirect_uri=<redirect uri>' \
      --data-urlencode 'client_id=<client id>' \
      --data-urlencode 'client_secret=<client secret>' \
      --data-urlencode 'state=<state string from step 1>'

OAuth token renewal request

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 refresh_token=<refresh token> \
  --form grant_type=refresh_token \
  --form scope=<scope1 scope2 scopeN>

OAuth token response

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

The Celonis API uses Bearer Token Authentication to verify consumer access. The credentials must be sent in an Authorization header in the HTTP request.

To authenticate using Bearer Token Authentication:

1. Call the token endpoint (https://< team-url >/oauth2/token) to issue a new token or renew an existing token.
2. Include the access_token in the HTTP Authorization header formatted like this:
   Authorization: Bearer #{access_token}

Scopes do not grant any additional permissions beyond what the client has. Instead, they specify the access-level that the client needs. Every scope has a name and a description, describing what can be accessed with the scope based on the permissions granted to the client.

For a list of available scopes, refer to the Available OAuth scopes help topic in the Celonis Documentation.

You must set the correct permissions for each grant type. For Client Credentials, permissions are defined on the OAuth client. For Authorization Code, the client inherits the permissions of the user who granted access.

For more information, refer to the OAuth 2.0 help topics in the Celonis documentation:

• Using OAuth 2.0
• Registering your OAuth client
• Available OAuth scopes
• Managing OAuth consent