Introduction #
The Account-level OAuth Client Credentials section is used when you wish to secure the following features within an Account:
- Webhook Steps in Cycles
- MCP Servers within that Account
- Data on Demand usage of the Cyclr API to call Methods on Connectors installed in that Account
Cyclr’s Webhooks and MCP Servers default to accepting and processing requests from any external system that has their unique URLs. If that’s not appropriate for your planned use, you can secure them using Cyclr’s Account-level OAuth Client Credentials.
Cyclr’s Data on Demand feature is always secured as the Cyclr API endpoints involved require an Access Token to be included in inbound requests. You can choose whether to use Console-level OAuth credentials, or create credentials at the Account-level which would only have access to Connectors within the Account they were created in. See Account-level Data on Demand for more details.
These Account-level credentials can then be shared with external systems or your customers.
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 they can then be used to obtain an Access Token through Cyclr’s API.
Depending on the Scope you set on the credentials, the token that’s retrieved can then be included in requests to a secured Cyclr MCP Server, a secured Cyclr Webhook, or in calls to the Cyclr API for Data on Demand usage.
Note: You can have up to 5 sets of OAuth credentials (Client ID and Client Secret) within a single Cyclr Account.
Usage #
Creating Client Credentials #
From within an Account (not your Cyclr Console):
- Select OAuth Client Credentials from the list of options on the left side.
- Select the + Generate Client Credentials button to create a new set of Cyclr credentials.
- Specify the following:
- Description – a name for this set of credentials to distinguish them from others.
- OAuth Client Scope – what the Cyclr feature is that these credentials will be used with.
Options are:- 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. Credentials with a “MCP” Scope can additionally have one or more Sign-in Tokens created for them, enabling separate users to be identified when using an MCP Server.
- Data On Demand – Access Tokens generated by these will only be valid for use when making calls to Cyclr API endpoints used in relation to Data on Demand for Connectors installed into 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.
- Select the Create button.
When working with MCP Servers within an Account, enabling the Require Authentication option will automatically create a new set of OAuth Client Credentials tied to that MCP Server. Disabling the toggle does not remove them.
Through testing and experimentation, you may therefore use up your maximum of 5 sets within an Account. If that happens, delete any you no longer need.
Obtaining an Access Token #
Having created a set of Cyclr OAuth Client Credentials – a Client ID and a Client Secret with a specific OAuth Client Scope value set – 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.
That Access Token can then be included in requests to a secured Cyclr MCP Server, Cyclr Webhook, or Cyclr’s API as part of making Account-level Data on Demand calls to execute Methods on Account Connectors.
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.
To make calls to the Cyclr API, see this Documentation article to identify the “Cyclr API Domain” value you should use in the following example.
Example Request
POST {CyclrAPIDomain}/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=XXXXXXXXXXXXXXXXXXXX&client_secret=XXXXXXXXXXXXXXXXXXXXExample 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, unless they have an OAuth Client Scope of “Data On Demand”, in which case they can be used for Data on Demand endpoints only.
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, exactly as before.
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.
Credentials using the “MCP” Scope #
When working with Cyclr’s MCP Servers, you have the option to secure each which means you must authenticate using OAuth Client Credentials. If you have a single system or application that you intend to allow to access your MCP Servers, then that might be all you need.
You could also choose to create multiple sets of OAuth Client Credentials within an Account, but be aware that each Account has a limit of 5 sets of Client Credentials (Client ID and Client Secret).
If you plan to give access to one or more Cyclr MCP Servers in a Cyclr Account to a whole team of individual users – each with their own LLM/AI agent system – you may wish to:
- have each user’s interactions logged separately within Cyclr, enabling you to see who’s doing what.
- be able to revoke individual user’s access.
To allow for this, after you’ve created a set of Account-level OAuth credentials using the “MCP” Scope, you can then create separate Sign-in Tokens – one for each of your users.
Sign-in Tokens #
When one or more Sign-in Tokens have been created for a set of OAuth Client Credentials, any attempts to use that set’s Client ID and Client Secret values will require an additional step where one of its Sign-in Token must then be provided as part of authenticating. See Authenticating with a Sign-in Token below.
When selecting the Manage Sign-in Tokens “key” button shown above, you are taken to a page where you can create and manage Sign-in Tokens for that set of credentials:
From there you can view existing Sign-in Tokens, whether they’ve ever been “used” (presented as part of authenticating with a Cyclr MCP Server) and also revoke access by deleting them.
Creating a Sign-in Token #
Select the + Add Sign-in Token button to create a new token:
In the popup that opens, the Description field enables you to provide text that will appear within Cyclr’s MCP Server Transactions, indicating which Sign-in Token – so which of your users – made each call to your MCP Server Tools.
Continuing by selecting the Create button will then display the new Sign-in Token:
This is displayed only once so be sure to make a note of it before selecting the Done button.
You can always delete the original and create a new Sign-in Token. That will revoke access if the original is being Used.
Authenticating with a Sign-in Token #
When a set of Account-level OAuth Client Credentials has one or more Sign-in Tokens created for it, providing one of those Sign-in Tokens becomes a required part of authenticating.
It effectively changes the type of authentication Cyclr uses with an MCP Server from “OAuth Client Credentials” into “OAuth Authorization Code”:
- No Sign-in Tokens created: only Client ID and Client Secret values are used to authenticate.
- With Sign-in Tokens created: the Client ID and Client Secret are initially provided, then a Sign-in Token is required to complete authentication.
Sign-in Tokens can only be used once. After being used to authenticate, they are no longer valid. This is to prevent impersonation, ensuring that only the person a Sign-in Token was intended for can use it.
Having enabled the Requires Authentication option for a Cyclr MCP Server and gone on to create Sign-in Tokens, when adding the MCP Server into an AI agent, you’ll need to provide the Client ID and Client Secret to begin authentication. How they are provided will depend on the LLM/AI agent used.
To complete authentication, the LLM/AI agent should then open a web browser to display a Cyclr page where one of the Sign-in Tokens related to that OAuth Client Credentials must be provided:
Having entered an unused Sign-in Token and selected the “Sign In” button, the user should be returned to the LLM/AI agent where they can then begin using the Cyclr MCP Server.