Account-level OAuth Client Credentials

The Account-level OAuth Client Credentials function is incorporated into Cyclr’s MCP Servers feature, which may not be enabled on your Cyclr Console.
If you’d like to discuss adding it to your existing Cyclr subscription, please get in touch with your Cyclr representative.

Introduction #

This feature is used to secure Cyclr MCP Servers and Cyclr Webhook Steps within Cyclr Accounts.

Generally, a Cyclr Webhook accepts and processes requests from any external system that has its unique URL. Cyclr’s MCP Servers can function in the same way, if required. Both can also be secured using Cyclr’s OAuth Client Credentials.

It’s always been possible to add your own Script to your Webhook Steps as a way to secure them. You could do that by checking an expected value is present in received requests, just as systems that use API Key authentication would.

With Cyclr’s OAuth Client Credentials, you can have Cyclr handle the authentication for you by using the standard OAuth 2.0 client credentials flow.

Overview #

This feature functions in the same way as the Console level OAuth Client Credentials, but is instead defined and used at the Cyclr Account level.

Within an Account, you create a set of OAuth credentials – which is a Client ID and a Client Secret – and use them to obtain an Access Token through Cyclr’s API. That token is then included when making requests to a Cyclr MCP Server or a Cyclr Webhook that has authentication enabled.

Usage #

Creating Client Credentials #

From within an Account:

1. Select OAuth Client Credentials from the list of options on the left side.
2. Select the + Generate Client Credentials button to create a new set of credentials.
3. Specify the following:
   • Description
     • A name for this set of credentials to distinguish them from others.
   • OAuth Client Scope
     • “Webhook”: Access Tokens generated by these will only be valid for use with Cyclr Webhooks within the Account.
     • “MCP”: Access Tokens generated by these will only be valid for use with Cyclr MCP Servers within the Account.
   • Minutes Tokens Will Expire After
     • The amount of time in minutes that Access Tokens obtained by this set of credentials are valid for. Determines how frequently an external system will need to obtain a new Access Token from Cyclr.
4. Select the Create button.

Obtaining an Access Token #

Having created a set of Client Credentials (a Client ID and a Client Secret) you would provide them to an external system to use. That system would make a call to the standard Cyclr API “OAuth Token endpoint” to obtain an Access Token to use in requests to either secured Cyclr MCP Servers or Webhooks.

The difference here is that you use the Client ID and Client Secret generated from within an Account, and not those from the Console level.

See this Documentation article to identify the Cyclr API Domain to use.

Example Request

POST {CyclrAPIDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=XXXXXXXXXXXXXXXXXXXX&client_secret=XXXXXXXXXXXXXXXXXXXX

Example Response

{
    "token_type": "bearer",
    "access_token": "XXXXXXXXXXXXXXXXXXXX",
    "expires_in": 1209600,
    "clientId": "XXXXXXXXXXXXXXXXXXXX"
}

The Access Token is returned as the value of the access_token property.

ℹ️ Access Tokens generated using Console level credentials are not valid with secured MCP Servers or Webhooks.

ℹ️ Access Tokens generated using Account level credentials are not valid for calls to the Cyclr API.

Access Token Expiry #

When generating an Access Token, Cyclr includes the standard expires_in property in its response to indicate when it will no longer be valid.

If no expiry has been set on the Client Credentials used, the default of 14 days will apply to any new Access Tokens (which is 1,209,600 seconds).

Once an Access Token has expired, calls made using it will result in an HTTP 401 Unauthorized error being returned by Cyclr MCP Servers and Webhooks.

A new Access Token should then be obtained by calling the POST {CyclrAPIDomain}/oauth/token Cyclr API endpoint again.

ℹ️ You can have multiple Access Tokens in use from the same set of Client Credentials, and each will expire independently. You also don’t need to wait until an existing Access Token has expired before obtaining a new one.