Support

The API is accessed with a user app token. To obtain this, you must first log in to the platform and create a token. After creating it, you will be presented with a 48-character long hexadecimal string, like this one: 

56115e8bee85630eba78a45cc804f1cae1545a701cd7a361

This is your token. It will only display once, please ensure you store it securely for future use in the application. 

When you make an API call, you must present this token (the long string of characters) to Cutover to prove you are allowed access to the resource you intend to retrieve, create, update or delete. The token is presented using an HTTP ^{Authorization} request header, which looks like this: 

Authorization: Bearer
56115e8bee85630eba78a45cc804f1cae1545a701cd7a361

This gets forwarded by the API to our Core application. The Core application looks in the database for a user app token with this string. If it finds one, it loads the user associated with that token and, providing that user has roles that gives them permission to do what they’re trying to do, then the request is successful. 

Yes. The token can only be used to do things that you would be able to do if you were logged in to Cutover. For example, if you are a Global User Admin then you would only be able to make API calls for the actions that a Global User Admin can carry out within the platform. 

As a user, you can have multiple tokens. This enables you to use different tokens in different applications or different scripts. Tokens require a label when created, so giving them a meaningful label is helpful if they later need to be deleted. 

Yes you do. For instance, you may want to revoke a token for a particular script that has run and will not be run again. Having an active token that is no longer being used creates a possible security risk where there does not need to be one. 

Read more in the 'Revoking API access' section of the Authentication page. Alternatively, you can make use of the API's Delete a user app token endpoint.

Your customer instance is not configured with token expiration by default, but this can be requested via your Customer Success Manager (CSM). You can contact our support team to adjust your instance's expiration period.

Note: This is a global setting on your instance, and therefore any expiry time that is set will apply to all tokens issued. It is not possible to make one token live longer than another.

Note: If token expiration is turned on in your instance, or if an existing expiry time is reduced, make sure that existing tokens in use were created recently enough to continue to be valid. 

You can also effectively manage your own token expiry via the API’s Create a new user app token and Delete a user app token endpoints.

For a long time, the general advice was to store them in environment variables where only your application could read them. This works well for simpler applications and smaller teams but it can get untidy. 

More recently, using encrypted secrets checked in to source control has become more popular. However, it’s important to know that the master key used to decrypt the secrets is not checked in to source control. 

Note: Never check an unencrypted token into source control. If you do, consider it compromised.

Alternatively, consider outsourcing your storage of credentials to a proven third-party secrets management product. 

Essentially impossible to guess, is the short answer. The token can be described as 192-bit and is thus practically unguessable given the astronomical amount of time and attempts needed to try all the possible combinations.  

You should revoke the token immediately (by deleting it) and create a new one. 

Read more in the 'Revoking API access' section of the Authentication page. Alternatively, you can make use of the API's Delete a user app token endpoint.

It will have the same effect as revoking the token and the token will no longer work.

The API requests rate limit is set at 500 requests a minute. If you feel you need a higher limit than this (for example, when performing bulk actions), please contact your Customer Success Manager (CSM) to discuss your requirements.