Authentication

Cyclr’s API uses the OAuth 2.0 Client Credentials flow for authentication.

There are several values you need in order to make calls to the Cyclr API:

• Client ID and Client Secret {client_id}, {client_secret}
• API Domain {CyclrAPIDomain}
• Access Token {access_token}
• Account API ID {API_ID}

Client ID and Client Secret #

You must generate these to be able to obtain an Access Token to make calls to the Cyclr API.

To view existing credentials, or generate a new set:

• go to your Cyclr Console.
• then go to Settings > OAuth Client Credentials.

To generate a new set:

1. Select + Generate Client Credentials.
2. Enter a description for the credential set and select the Create button.
3. The page displays the new Client ID next to the time it was created.

At any point you can return to this page and select the “eye” button to view a credential set’s Client Secret value:

API Domain #

The API domain you use to make calls to Cyclr’s API depends on where your Cyclr Console is hosted.

See here for details on how to identify the domain.

Note: Replace {CyclrAPIDomain} in the example calls below with the correct API Domain for your Cyclr Console’s location.

Access Token #

Calls to the Cyclr API must include an Access Token in the Authorization HTTP request header as a Bearer token, e.g.:

Authorization: Bearer {access_token}

Access Tokens are valid for 14 days so you must generate a new one when it expires to continue using the Cyclr API.

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.

Obtaining a Cyclr API Access Token #

Once you have a Cyclr Client ID and Client Secret, you can call the Cyclr API OAuth token endpoint to generate an access token.

Example Request

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

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Parameters

These are passed in the Request Body:

Parameter	Description
grant_type	Specify client_credentials to identify the OAuth flow.
client_id	Enter the Client ID to identify which Cyclr Console the token is for.
client_secret	Enter the matching Client Secret.

Example Response #

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

Response Parameters

Parameter	Description
token_type	The type of token Cyclr’s API returns is always bearer.
access_token	The Access Token you can use to make requests to the Cyclr API.
expires_in	The amount of time in seconds until the Access Token expires, which is 14 days, or 1,209,600 seconds.
clientId	The Client ID provided when the request was made.

Account API ID #

For calls to Cyclr API endpoints that relate to a Cyclr Account, you need to provide the Account’s API ID as an HTTP header in the request:

X-Cyclr-Account: {API_ID}

To view an Account’s API ID, in your Cyclr Console, go to Accounts > Account Management and select the Settings icon for the Account you wish to work with. The API ID appears towards the top of the page.

Account Restricted Access Tokens #

You can restrict Access Tokens to only work for a specific Cyclr Account by including the API ID in a scope parameter when you make the access token request:

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

grant_type=client_credentials&client_id=abcdefg&client_secret=abcdefghij123&scope=account:{API_ID}