{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/celonis-apis/auth/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Authentication

\n

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

\n

About authentication options

\n

Static Keys

\n

To be discontinued / sunsetting milestones will be officially announced.

\n

While it is possible to use API keys and Application keys with Celonis, it's important to note that they are not the industry standard and are therefore not recommended. Both keys have an unlimited lifetime and cannot be “rotated”. This means that users need to delete and recreate them to achieve the equivalent of key rotation, which can be a cumbersome process.

\n

One issue (particularly relevant for API Keys) is that they give any application that uses them complete access to almost all the Celonis APIs (public or private). There is no way to restrict their access to only certain resources.

\n

OAuth 2.0 as the Recommended Solution

\n

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.

\n

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.

\n

Migration from a static key to OAuth 2.0

\n

If a 3P application is using an API key or Application key to integrate with Celonis, they should migrate to OAuth 2.0 as soon as possible using the process below:

\n
    \n
  1. \nCreate an OAuth 2.0 client as described in the \nUsing an OAuth 2.0 token\n section.\n
    2. \n
  2. \nGive the new OAuth 2.0 client permissions on the same packages as your existing Application Key or existing user.\n
    3. \n
  3. \nConfigure 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.\n
    4. \n
  4. \nRefresh and redirect (optional for \nauthorization code\n grant type) URLs using the endpoints and requests described in the \nOAuth Endpoints\n section.\n
    5. \n
\n

Using a User API key

\n

To be discontinued / sunsetting milestones will be officially announced.

\n

You can find out how to create a user API key by following\nour User API Keys\nguide.

\n

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.

\n

To authenticate using Bearer Token Authentication:

\n
    \n
  1. \nCreate the token in the Celonis Platform: \n
    \n\n\nMDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM\n
    2. \n
  2. \nInclude the string in the HTTP Authorization header formatted like this: \n
    \n\n\n\nAuthorization: \n\nBearer\n\n\nMDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM\n\n
    3. \n
\n

Using an Application API key

\n

To be discontinued / sunsetting milestones will be officially announced.

\n

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

\n

To authenticate using AppKey Authentication:

\n
    \n
  1. \nCreate the AppKey in the Celonis Platform: \n
    \n\n\nMzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr\n
    2. \n
  2. \nInclude the string in the HTTP Authorization header formatted like this: \n
    \n\n\n\nAuthorization: \n\nAppKey\n\n\nMzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr\n\n
    3. \n
\n

Using an OAuth 2.0 token

\n

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

\n

OAuth client Grant Types

\n

Client Credentials

\n

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

\n

Authorization Code

\n

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. This capability is in private preview. Contact your Celonis account team to get early access.

\n

OAuth client Authentication Methods

\n

Client secret basic

\n

With this method, the client sends the $client_id and $client_secret using the Authorization header, in the following format:

\n\n

Here, the value of $encoded_credentials corresponds to the base64 encoding of OAuth client’s $client_id:$client_secret.

\n

Client secret post

\n

The client authenticates 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.

\n

Registering an OAuth client in Celonis Platform

\n

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.

\n
    \n
  1. \nIn the Celonis Platform, go to \nAdmin & Settings\n. \n\n \n \n \n
    2. \n
  2. \nIn the upper-right corner, click \nAdd New Application\n and select \"OAuth Client\". \n\n \n \n \n
    3. \n
  3. \nEnter a name for your client.\n
    4. \n
  4. \nSelect one of the supported \nOAuth grant types\n: \"Client Credentials\" or \"Authorization Code\". \n\n \n \n \n
    5. \n
  5. \nSelect one of the supported \nOAuth authentication methods\n: \"Client secret basic\" or \"Client secret post\". \n\n \n \n \n
    6. \n
  6. \nClick \nDefine scopes\n. Scopes do not grant any additional permissions beyond what the client has, but instead they specify the access-level that the client needs. Select what levels within the Celonis Platform the clients will have access to based on their 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.\n
    7. \n
  7. \nClick \nCreate\n.\n
    8. \n
\n

As scopes only allow access to the APIs, the created OAuth client should now be assigned permissions to the resources behind those APIs.

\n

After creating a client in the Celonis Platform, developers receive client credentials: client ID and client secret. The client secret must be copied as it cannot be accessed again in the future.

\n

IMPORTANT: For production solutions, we strongly recommend using OAuth 2.0 instead of static keys.

\n

OAuth Endpoints

\n

The access and refresh token URL

\n

The token endpoint is available at https://< team-url >/oauth2/token.

\n

The redirect URL

\n

This endpoint is specified by the consumer.

\n

OAuth Requests

\n

OAuth token generation request (client_credentials)

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

OAuth token generation request (authorization_code)

\n
\n
..celonis.cloud/oauth2/token \\\\\n --header 'content-type: multipart/form-data' \\\\\n --form client_id= \\\\\n --form grant_type=authorization_code \\\\\n --form response_type=code \\\\\n --form redirect_uri= \\\\\n --form scope=`, `69132570829472840000`)\"\n >\n
Copy
\n
Copied
\n
\n 
curl --request POST \\\n  --url https://<team>.<cluster>.celonis.cloud/oauth2/token \\\n  --header 'content-type: multipart/form-data' \\\n  --form client_id=<client id> \\\n  --form grant_type=authorization_code \\\n  --form response_type=code \\\n  --form redirect_uri=<redirect uri> \\\n  --form scope=<scope1 scope2 scopeN>
\n
\n

OAuth token renewal request

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

OAuth token response

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

Regenerating the OAuth client secret

\n

For security reasons, you may need to regenerate the client secret.

\n
    \n
  1. \nNavigate to \nAdmin & Setting > Applications\n.\n
    2. \n
  2. \nFind the OAuth client. \n
    3. \n
  3. \nClick the three dots menu on the right and select \nRegenerate Secret\n.\n
    4. \n
\n

After generating the new client secret, make sure to update it in any integration where this client is used.

\n

Managing OAuth Client Consent

\n

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:

\n
    \n
  1. \nNavigate to \nEdit Profile\n.\n
    2. \n
  2. \nGo to the \nOAuth Client Management\n section to view which applications (OAuth clients) have been granted consent. \n
    3. \n
  3. \nYou can also revoke a consent by clicking on \nEdit\n and then selecting \nRevoke Consent\n for the corresponding client.\n
    4. \n
\n

How to use OAuth tokens

\n

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

\n

NOTE: Credentials sent in the URL or body of the request will be ignored.

\n

To authenticate using Bearer Token Authentication:

\n
    \n
  1. \nCall the token endpoint (\nhttps://< team-url >/oauth2/token\n) to issue a new token or renew an existing token.\n
    2. \n
  2. \nInclude the \naccess_token\n in the HTTP Authorization header formatted like this: \n
    \n\n\n\nAuthorization: \n\nBearer\n\n\neyJraWQiOiJkZXZlbG9wLWVzMzg0IiwiYWxnIjoiRVMzODQifQ.eyJhdWQiOlsiYjllMzgwZDYtMmUxZS00MmQ5LWI3YjUtZTJkZDI5MGYxZTU5IiwiYXBpbmF1dHMuZGV2ZWxvcC5jZWxvbmlzLmNsb3VkIl0sIm5iZiI6MTcxMjEzNDU4NywiYXpwIjoiYjllMzgwZDYtMmUxZS00MmQ5LWI3YjUtZTJkZDI5MGYxZTU5Iiwic2NvcGUiOlsib3BlbmlkIl0sImlzcyI6Imh0dHBzOi8vYXBpbmF1dHMuZGV2ZWxvcC5jZWxvbmlzLmNsb3VkIiwiZXhwIjoxNzEyMTM1NDg3LCJpYXQiOjE3MTIxMzQ1ODcsImp0aSI6IjI2ZjlhNTU3LWQwMTEtNDcyNy05MTNhLWU3NmU3MDIzMTkyMyJ9.XIBj89ymumPaDL\nInAsuWiL\n6e5GeMpDGgPz3cZNWF3rNzNTc4GRAXMrtBjU9Gg6SWpyqPK0tTaTsrf88fmc0MboYXvKH0CxtpqWlDp0h_QSRMb1ZsCD226kv83xbh86\n\n
    3. \n
\n

Video

\n\n

Authorization

\n

Scopes

\n

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.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Scope NameScope Description
intelligence.knowledge-models:readAllows read access to Knowledge Models and their data, filters, records, KPIs, OData metadata, specs, and triggers (based on granted permissions).
intelligence.subscriptions:manageAllows managing subscriptions to Knowledge Model triggers, including creation, updates, and event replay, based on granted permissions.
intelligence.tools:executeAllows executing AI Copilot Tools, based on granted permissions.
intelligence.conversations:writeGives access to Studio Copilot conversational API.
user-provisioning.scimGives access to the SCIM API.
audit.log:readGives read-only access audit logs.
integration.data-poolsGives access to data pools.
integration.data-pools:data_pushGives access to push data to data pools.
integration.data-pools:continuous_data_pushGives access to continuously push data to data pools.
platform-adoption.tracking-events:readGives read-only access to platform-adoption tracking-events.
team.user-group-info:readGives read-only access to team user and group information.
team.login-history:readGives read-only access to team login history.
task-mining.gatewayGives access to Task Mining Gateway integration API.
task-mining.metadata:readGives read-only access to Task Mining user metadata.
action-engine.projectsGives access to projects.
\n

Permissions

\n

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 resources you would like to access through the APIs.

","headings":[{"value":"Authentication","depth":1},{"value":"About authentication options","depth":2},{"value":"Static Keys","depth":3},{"value":"OAuth 2.0 as the Recommended Solution","depth":3},{"value":"Migration from a static key to OAuth 2.0","depth":3},{"value":"Using a User API key","depth":2},{"value":"Using an Application API key","depth":2},{"value":"Using an OAuth 2.0 token","depth":2},{"value":"OAuth client Grant Types","depth":3},{"value":"Client Credentials","depth":4},{"value":"Authorization Code","depth":4},{"value":"OAuth client Authentication Methods","depth":3},{"value":"Client secret basic","depth":4},{"value":"Client secret post","depth":4},{"value":"Registering an OAuth client in Celonis Platform","depth":3},{"value":"OAuth Endpoints","depth":3},{"value":"The access and refresh token URL","depth":4},{"value":"The redirect URL","depth":4},{"value":"OAuth Requests","depth":3},{"value":"Regenerating the OAuth client secret","depth":2},{"value":"Managing OAuth Client Consent","depth":2},{"value":"How to use OAuth tokens","depth":2},{"value":"Video","depth":1},{"value":"Authorization","depth":1},{"value":"Scopes","depth":2},{"value":"Permissions","depth":2}]},"contentItem":{"data":{"lastModified":"2025-11-11T20:55:07.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":false,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"c2c6496a-aa0e-5b78-9a7e-9a340a164d44__redocly content/celonis-apis/auth/","seo":{"title":"Authentication","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"celonis-apis/auth.md","pageBaseUrl":"/celonis-apis/auth","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Authentication","id":"authentication"},{"depth":2,"value":"About authentication options","id":"about-authentication-options"},{"depth":3,"value":"Static Keys","id":"static-keys"},{"depth":3,"value":"OAuth 2.0 as the Recommended Solution","id":"oauth-20-as-the-recommended-solution"},{"depth":3,"value":"Migration from a static key to OAuth 2.0","id":"migration-from-a-static-key-to-oauth-20"},{"depth":2,"value":"Using a User API key","id":"using-a-user-api-key"},{"depth":2,"value":"Using an Application API key","id":"using-an-application-api-key"},{"depth":2,"value":"Using an OAuth 2.0 token","id":"using-an-oauth-20-token"},{"depth":3,"value":"OAuth client Grant Types","id":"oauth-client-grant-types"},{"depth":4,"value":"Client Credentials","id":"client-credentials"},{"depth":4,"value":"Authorization Code","id":"authorization-code"},{"depth":3,"value":"OAuth client Authentication Methods","id":"oauth-client-authentication-methods"},{"depth":4,"value":"Client secret basic","id":"client-secret-basic"},{"depth":4,"value":"Client secret post","id":"client-secret-post"},{"depth":3,"value":"Registering an OAuth client in Celonis Platform","id":"registering-an-oauth-client-in-celonis-platform"},{"depth":3,"value":"OAuth Endpoints","id":"oauth-endpoints"},{"depth":4,"value":"The access and refresh token URL","id":"the-access-and-refresh-token-url"},{"depth":4,"value":"The redirect URL","id":"the-redirect-url"},{"depth":3,"value":"OAuth Requests","id":"oauth-requests"},{"depth":2,"value":"Regenerating the OAuth client secret","id":"regenerating-the-oauth-client-secret"},{"depth":2,"value":"Managing OAuth Client Consent","id":"managing-oauth-client-consent"},{"depth":2,"value":"How to use OAuth tokens","id":"how-to-use-oauth-tokens"},{"depth":1,"value":"Video","id":"video"},{"depth":1,"value":"Authorization","id":"authorization"},{"depth":2,"value":"Scopes","id":"scopes"},{"depth":2,"value":"Permissions","id":"permissions"}]},"data":{"title":""},"catalogInfo":null,"link":"/celonis-apis/auth/","sidebarName":"celonis","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}