Support

Welcome to the Developer Portal Support page, where you can find out how to contact us directly or read our FAQs.

Frequently Asked Questions

How is access to the API granted?

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
  
Copy to clipboard

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

How is the user app token used?

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. 

Are user app tokens linked to a user?

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. 

How many user app tokens can a user have?

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. 

A screenshot of the 'new user app token' interface

Do I have the ability to revoke user app tokens?

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.

A screenshot of the 'revoke user app token' button

Do user app tokens expire after a given amount of time?

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.

What is best practice for storing user app tokens?

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. 

How guessable are user app tokens?

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.  

What should I do if I think a user app token has been compromised?

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.

What happens to a token if a user is archived?

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

What should I do if I want to raise my API requests rate limit?

The API requests rate limit is set at 60 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. 

Cookie consent

By clicking “Accept”, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Privacy Policy for more information.