Token Rotation Guide

This guide covers the basic concepts to allow you to elevate application security when using our Public API Tokens.

Overview

Our public data access credentials are meant to be used in data applications and end-customer interfaces. This means that users on the internet can take your token and use it without your permission.

To address the risk with abused public credentials, in Fall 2024 we are releasing the ability to restrict the origin host for tokens used on webpages. This can reduce the need for token rotation. Learn more

Rotation is the recurring exchange of the existing token for a new token. By regularly invalidating the existing token in favor of a new one, anyone who has manually copied your token will be required to update their application. 

Benefits

Rotation allows you to

• Carefully control where your token is used

• Use tokens with shorter expiration times to minimize credential theft issues

Even after we release our new token use controls it is still best practice to rotate the token in your applications regularly to ensure you know exactly what uses of your tokens exist, and to avoid any issues with expiring tokens. By default Synoptic tokens do not expire for a very long time (10+ years). 

Basic rotation function

To rotate a token, you would want to:

1. Generate a new token

2. Distribute it to your applications

3. Disable the existing token

In that order, to prevent outages. There are many ways to perform this action, and how you do it depends on how your applications work. It is not recommended to disable the existing token at the same time as you generate a new one, as this can cause unnecessary service outages for your application users.

Rotation frequency is a function of your design, but we recommend between 1 and 30 day rotation periods. Additionally it is you may want to have up to one entire additional rotation period where the prior token is left valid, to allow your applications to self-update to the latest credential without any service interruption. 

Synoptic does not use refresh tokens you may be familiar with more sensitive Oauth2 implementations. Our tokens are all issued in a single interaction and must be made available to your client applications by your own implementation.

Generating a new token

Synoptic’s credential admin APIs offer programmatic control of your public tokens, including creating, listing and disabling. Using your private API Key (which should be protected from external use, as this cannot be rotated programmatically) you can generate a new token with the following options

• Define the expiry time using the expire argument (recommended, this automates the disable process, so you don’t have to worry about it)

• Copy functional token settings from an existing valid token using the cloneSettings argument (if the token you are rotating has some special characteristics - including settings like public-only data access or origin restriction settings)

By making a request to the Credential API Service with the designated settings, you will receive a token to use in place of the existing token.

Distribute token to applications

How you take a newly created token and make it available to end applications is flexible. What is important is that Synoptic does not have any services that are usable for this purpose. You should not request the token list endpoint from a client, as this would require the client to access your private key.

You may want to publish the new token in a location internally or publicly fetchable where your applications know to periodically check for an updated token. Systems where tokens are fetched from secret stores or environment variables can have those fields/services updated.

As noted above, ensure your token expiration settings are sufficient to permit this distribution to complete before the rotated-out token expires.

Deleting the existing token

The best way to delete a rotating token is to set the expire date/time when generating the token. Then the token will stop working at that time without any additional effort..

As noted above, ensure that there is sufficient overlap in the expiration time for the distribution of the new token to complete. This is a function of your token rotation frequency and the method used by your application to update token values.

Using your API Key and the credential API service you can delete a token manually/explicitly. You can do this even if your token has an expiration time defined.

You have less than 60 seconds from disabling a token to it no longer answering queries globally

You cannot edit the expiration time of a token once generated.

Synoptic resources for rotating tokens

Our token admin API endpoints are the best place to manage tokens when you will be rotating them. From there you can create, list, disable, and set the expiration date for tokens.

The customer web console also works well for manually creating and viewing your tokens, in addition to having the option to delete tokens.

For any questions regarding best practices with public data access credentials, reach out to support@synopticdata.com.