Skip to main content
Rotation replaces the secret of an existing token with a new one while keeping everything else — the token ID, name, and scopes — intact. Use rotation as a proactive security measure on a regular schedule or any time you want to cycle credentials without interrupting access. Unlike revocation, rotation keeps the token alive; only the secret changes.

​
Rotation vs. revocation

RotationRevocation
Token IDUnchangedUnchanged (record retained)
ScopesUnchangedN/A
SecretReplaced with a new valuePermanently invalidated
Token statusactiverevoked
ReversibleNo (old secret is gone)No
Choose rotation when you want to cycle credentials on a schedule or in response to a potential exposure. Choose revocation when you want to permanently end access.

​
When to rotate

  • Scheduled security hygiene — rotate long-lived service tokens on a quarterly or monthly cadence as part of your security policy.
  • Pre-emptive credential cycling — rotate before decommissioning an environment or handing a project to another team.
  • Suspected but unconfirmed exposure — if you are not certain a secret was exposed but want to eliminate the risk, rotation is less disruptive than revocation because it keeps the token ID stable.
The old secret is invalid the moment you call POST /tokens/:id/rotate. Update the secret in all dependent services before making this call, or be prepared to deploy the new secret immediately after.

​
Zero-downtime rotation strategy

Follow these steps to rotate a token without dropping requests in production.
1

Call the rotate endpoint

Send POST /tokens/:id/rotate to generate the new secret. The response contains the new token value. Store it securely — it is shown only once.
2

Update your secrets store

Write the new secret to your environment variable, secrets manager entry (AWS Secrets Manager, HashiCorp Vault, etc.), or CI/CD secret. Do not restart your service yet.
3

Redeploy or restart the service

Trigger a rolling restart or redeploy so the service picks up the new secret from the environment. Orchestrators like Kubernetes will drain old pods gradually, ensuring in-flight requests complete before the old secret stops being used.
4

Verify the new secret works

Make a test request using the new secret and confirm you receive a successful response. Check your monitoring dashboards for any 401 Unauthorized errors that could indicate a service still using the old secret.

​
Rotate a token

curl --request POST \
  --url https://api.tooken.io/v1/tokens/tok_a1b2c3d4e5f6g7h8i9j0k1l2/rotate \
  --header 'Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx'
A successful rotation returns 200 OK with the following body:
response
{
  "id": "tok_a1b2c3d4e5f6g7h8i9j0k1l2",
  "token": "eyJnZXciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scopes": ["tokens:read", "tokens:write"],
  "rotated_at": "2024-09-01T08:00:00Z"
}
The token field contains the new secret. The id and scopes are unchanged. Store the new secret immediately — it is not retrievable again after this response.

​
Automate rotation on a schedule

For long-lived service tokens, automate rotation using a cron job or your cloud provider’s scheduled task service. Call POST /tokens/:id/rotate on your chosen cadence, write the new secret to your secrets manager, and trigger a rolling restart. This keeps credentials fresh without manual intervention.
Here is a minimal Node.js script you can run as a cron job:
rotate-token-cron.js
import { SecretsManagerClient, UpdateSecretCommand } from '@aws-sdk/client-secrets-manager';

const TOOKEN_API_KEY = process.env.TOOKEN_API_KEY;
const TOKEN_ID = process.env.TOKEN_ID; // e.g. tok_a1b2c3d4e5f6g7h8i9j0k1l2
const SECRET_ARN = process.env.SECRET_ARN; // AWS Secrets Manager ARN

async function rotateToken() {
  // 1. Rotate the token in Tooken
  const response = await fetch(
    `https://api.tooken.io/v1/tokens/${TOKEN_ID}/rotate`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${TOOKEN_API_KEY}` },
    }
  );

  if (!response.ok) {
    throw new Error(`Rotation failed: ${response.status}`);
  }

  const { token: newSecret } = await response.json();

  // 2. Write the new secret to AWS Secrets Manager
  const client = new SecretsManagerClient({});
  await client.send(new UpdateSecretCommand({
    SecretId: SECRET_ARN,
    SecretString: JSON.stringify({ token: newSecret }),
  }));

  console.log('Token rotated and secret updated successfully.');
}

rotateToken().catch(console.error);

​
Next steps

Revoke a token

Permanently invalidate a token when rotation is not sufficient.

Integrate with your stack

Learn how to store and use Tooken tokens safely across CI/CD, environment variables, and secrets managers.