Rotate an API key

Rotation replaces a key without changing what it can do. In a single database transaction the server revokes the old key (identified by {id}) and creates a brand-new key that inherits the old one's name, scopes, rate_limit, and is_default flag. The old key stops authenticating immediately; the new key takes its place. Use this when a secret may have leaked, on a periodic rotation schedule, or whenever you want a fresh value without re-creating and re-configuring a key by hand.

This is a console (dashboard) endpoint, not an RPC endpoint — it uses the same cookie-session scheme as the rest of /v1/auth/* and /v1/keys. There is no API-key or Bearer-token form for calling it. Because rotation mutates state, the request must carry the X-CSRF-Token header whose value matches the nl_csrf cookie set at login.

The raw key is shown once. The raw field in the response is the only time the full new secret is ever returned — exactly like creating a key. Every other endpoint (list, this response's new object on later reads) returns only the 8-character key_prefix. Capture raw and store it securely before the response is discarded; it cannot be recovered afterward.

Path parameters

Response fields

Errors use the shared error envelope { "error": "<code>" }. See errors.md for the full envelope and handling guidance.

JavaScript (fetch)

function readCookie(name) {
  const m = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
  return m ? decodeURIComponent(m[1]) : null;
}


const keyId = "3f2c1b9a-5e4d-4c8b-a1f0-9d7e6c5b4a3f";


const res = await fetch(`https://api.triport.io/v1/keys/${keyId}/rotate`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
    "X-CSRF-Token": readCookie("nl_csrf") ?? "",
  },
});


const { old_id, new: newKey, raw } = await res.json();
// `raw` is shown once — persist it now.
console.log(`Rotated ${old_id} -> ${newKey.id}`);

TypeScript SDK (@triport/sdk)

import { TriportConsole } from "@triport/sdk";


const console = new TriportConsole({ baseUrl: "https://api.triport.io" });


// Returns { oldId, key, raw }. `raw` is only available on this call.
const { oldId, key, raw } = await console.keys.rotate(
  "3f2c1b9a-5e4d-4c8b-a1f0-9d7e6c5b4a3f",
);


saveSecret(raw); // store before it is lost

Python (triport-sdk)

from triport import ConsoleClient


console = ConsoleClient(base_url="https://api.triport.io")


# Session cookie + CSRF are managed by the client.
result = console.keys.rotate("3f2c1b9a-5e4d-4c8b-a1f0-9d7e6c5b4a3f")


print("old:", result.old_id, "new:", result.new.id)
save_secret(result.raw)  # raw is returned only once

• Inheritance, not configuration. Rotation copies name, scopes, rate_limit, and is_default from the old key. To change any of those, rotate first and then edit the new key (or create a fresh key with create-key).
• The old key dies immediately. Revocation and creation happen in one transaction, so there is no overlap window where both keys authenticate. Deploy the new raw value to your clients as part of the rotation, not before.
• Default key is preserved. Rotating the account's default key produces a new key that is still the default — no separate step is needed to keep it default.
• Idempotency / retries. Rotation is not idempotent: each successful call mints a new secret and revokes the previous one. A rotate_conflict (409) means a concurrent rotation won the race — re-list the key with list-keys and retry against the current active key rather than blindly re-sending.
• Related: create-key, list-keys, revoke-key, and the session model.