Replace the key you are calling with.

POST

/me/keys/rotate

const url = 'https://testnet.permafrost.live/me/keys/rotate';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://testnet.permafrost.live/me/keys/rotate \
  --header 'Authorization: Bearer <token>'

Mints a fresh key with the same permissions and revokes the key that made this request, in one step. There is no window in which both work.

raw_key is shown once. It is not stored anywhere it can be read back, and no route returns it again. Switch to it immediately — the key in the Authorization header of this very request is already revoked by the time the response arrives.

Key lane only, for the same reason GET /me is.

Authorizations

bearerAuth

Responses

201

The new key. Read raw_key now or lose it.

application/json

The freshly minted key, and the id of the one it replaced.

object

raw_key

required

The new key, shown once. No route returns it again.

string

key_id

required

string format: uuid

key_prefix

required

string

permissions

required

Array<string>

revoked_key_id

required

The key that made this request. It no longer authenticates anything.

string format: uuid

Example

{
  "raw_key": "pf_sk_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "key_id": "0a7c4e18-2b93-4f06-8d5a-1c6e9b3f2d47",
  "key_prefix": "pf_sk_0f1e2",
  "permissions": [
    "read",
    "write"
  ],
  "revoked_key_id": "5e2b9a71-4c08-4d3f-91b6-7a0d2f8c1e34"
}

401

No usable pf_sk_ on the request. Absent, malformed, unknown, revoked, or belonging to a tenant that is no longer active — one answer for all of them. A caller on the token lane lands here too: this route authenticates by key, and a token holder has no key to present.

application/json

The refusal shape. detail is present on a few routes and deliberately absent from the custody surface, where a detail string could carry an internal path.

object

error

required

The code, or a short fixed sentence.

string

detail

A human-readable note, where a route carries one.

string

Example

{
  "error": "invalid or inactive API key"
}

Permafrost runs on Sui testnet and Walrus testnet. Everything here describes a shipped testnet instance, not a production service.