Rotate API Tokens

Token rotation is the practice of replacing a token with a new one. Rotating a token limits how long it can be used if it is ever leaked.

Contentstack does not rotate tokens for you. You rotate a token by creating a new one, updating the applications that use it, and then deleting the old one. This guide explains when to rotate each token type and how to do it without interrupting your applications.

Whether to rotate a token on a schedule depends on what the token can do:

• Management Tokens have read and write access to your stack through the Content Management API. Anyone who holds one can create, update, publish, and delete content. Rotating Management Tokens regularly is a recommended security practice.
• Delivery Tokens are read-only. They fetch published content from one environment through the Content Delivery API and cannot change or delete your data. You do not need to rotate Delivery Tokens on a schedule. Rotate a Delivery Token only if it has been exposed and is being misused, for example to send a large number of API requests to your stack.

Note User Authtokens and OAuth access tokens are tied to a user session and are renewed by logging in again or by the OAuth refresh flow. This guide covers Management Tokens and Delivery Tokens.

• Management Tokens: when you generate one, you choose its expiry under Expiry: Never, or a Date (in UTC). A dated token expires at midnight UTC on that date, and the Content Management API then rejects it. You can enable Notify via email to receive a reminder 7 days before the token expires. You can change the expiry date later by editing the token.
• Delivery Tokens: a Delivery Token does not expire, and its value cannot be edited. To use a different token value, you create a new Delivery Token.

Only the stack Owner or Admin can generate and delete Management Tokens. Create the replacement before you delete the old token, so your processes always have a valid token.

To rotate a Management Token, log in to your Contentstack account, go to your stack, and perform the following steps:

1. Generate a new Management Token with the same Scope, permissions, and rate limits as the token you are replacing.
2. Under Expiry, select Date and choose when this token should expire, then enable Notify via email so you are reminded before it does.
3. Copy the new token from the confirmation window. You cannot view it again after you close the window.
4. Update the token wherever the old one is stored, such as your secrets manager, CI/CD pipelines, migration scripts, or integrations.
5. Run the processes that use the token and confirm that their Content Management API requests succeed.
6. Delete the old Management Token.

Note By default, a stack can hold up to 20 Management Tokens. To increase this limit to 30, contact Contentstack Support. If your stack is at the limit, delete a token that is no longer used before you generate the replacement.

If a Management Token may have been exposed, for example committed to a public repository or included in a log, do not wait for its scheduled rotation. Delete it, or edit it and set its expiry date to the current day, and then generate a replacement.

If a Delivery Token has been exposed and is being used to make unwanted requests to your stack, replace it. By default, a stack can hold up to 20 Delivery Tokens, and you can increase this limit to 50 by contacting Contentstack Support. If your stack is at the limit, delete a token that is no longer used before you create the replacement.

To rotate a Delivery Token, log in to your Contentstack account, go to your stack, and perform the following steps:

1. Create a new Delivery Token with the same Branches or Aliases scope and the same Publishing Environments as the token you are replacing. If your applications use a Preview Token, enable Create Preview Token.
2. Copy the new token values and update them wherever the old token is stored, such as your environment variables, secrets manager, CI/CD configuration, or hosting provider.
3. Redeploy or restart the applications that read the token, and confirm that they fetch content successfully with the new token.
4. Delete the old Delivery Token. Its associated Preview Token is deleted with it.

Warning Deleting a Delivery Token ends all sessions associated with it, and it cannot be undone. Any application still using the old token stops receiving content, so delete it after every application has switched to the new token. If the unwanted requests must stop at once, delete the old token first and update your applications immediately after.

You can rotate tokens with the Content Management API Tokens requests, which create and delete Management Tokens and Delivery Tokens. A rotation script follows the same order as the steps above: create the new token, update your secret store, verify, then delete the old token.

Note A Management Token cannot be used to create or delete tokens. Authenticate token requests with a user Authtoken or OAuth.

• Set an expiry date on every Management Token, and enable Notify via email so that you can plan each rotation before the token expires.
• Rotate Management Tokens on a regular schedule that meets your organization's security policy, and whenever someone with access to a token leaves your team.
• Create a separate token for each application, environment, and pipeline. You can then rotate or revoke one without affecting the others.
• Grant each Management Token only the branches, aliases, and permissions it needs.
• Store tokens in a secrets manager or environment variables. Never commit them to source control or expose a Management Token in client-side code.
• Give each token a Name and Description that identify where it is used, so you know what to update when you rotate it.
• Review your tokens periodically and delete any that are unused. The Healthcheck app flags expiring and unused tokens.