Skip to content

Rotate, Expire, Revoke

Replace an API client's token, limit how long it works, or stop it for good, in MetaMiner Administrator (MMA) or over the API.

Action Effect Same token afterwards?
Rotate A new token is issued; the previous one stops at once on every node No
Expire After the expiry date the token gets 401 Yes, if you extend the expiry
Revoke The token stops at once on every node; the client stays listed as Revoked No, never

Before you begin

  • You have a secrets vault ready to receive a new token.
  • In a high-availability pair with the Flow Scheduler switched on, make these changes on the leader (see Changes only on the leader).
  • Over the API, changing another client needs an admin client without environment or site limits. Any client may rotate its own token.

Rotate a token

Store the new token first

The previous token stops working the moment the rotation succeeds. Save the new token in your vault before you discard the old one, and roll it out to every script that uses the client.

In MMA

  1. In MMA, choose Preferences > Settings..., open Advanced and click Manage API Clients....
  2. Select the client and click Rotate Token....
  3. Confirm in the Rotate Token dialog. The API Client Token dialog shows the new token once.
  4. Click Copy and store the token in your vault.

Over the API

A client rotates its own token with POST /fss/v1/clients/me/rotate, sending its current token as the bearer. An admin client without environment or site limits rotates another client with POST /fss/v1/clients/{name}/rotate.

curl -sS -X POST "https://<mms-host>:<port>/fss/v1/clients/me/rotate" \
  -H "Authorization: Bearer <token>"

$r = Invoke-RestMethod -Method Post -Uri "https://<mms-host>:<port>/fss/v1/clients/me/rotate" `
  -Headers @{ Authorization = "Bearer <token>" }
$r.token   # store this now
Answer (200)
{"name": "secrets-rotation", "token": "mmsk_...", "note": "The previous token no longer works. Store this one now: it is shown only once."}
Status Meaning
200 Rotated. The answer carries the new token.
400 me/rotate was called under Local only: the call carries no client token
401 The token is not that of an active client
403 {name}/rotate by a client that may not manage clients
404 {name}/rotate for an unknown or revoked client
409 NOT_LEADER: sent to the standby node; the answer names the leader
503 API_CLIENTS_UNAVAILABLE: the clients cannot be checked. Retry.

An expired client can also be rotated. Rotation does not change its expiry.

Deprecated: POST /apitoken/rotate

Deprecated

POST /apitoken/rotate is kept for one release only. Move scripts to POST /fss/v1/clients/me/rotate, which generates the new token for you.

The call sends the current token as the bearer and the new token in the body, either raw or as {"token":"<new token>"}. It sets the calling client's token to the one supplied and answers 200 with {"status":"ok","message":"API token rotated"}.

Status Meaning
400 No new token in the body, or the new token equals the current one
401 / 503 As for me/rotate
404 The mode is Local only: the endpoint does not exist
409 Sent to the standby node
413 Body over 64 KiB

Set or extend an expiry

  1. In the API Clients window, select the client and click Edit....
  2. In Expires:, choose None (never expires), 30 days, 90 days or 365 days. Keep: expires (or Keep: expired ) leaves the expiry as it is.
  3. Click Save.

Over the API, send PUT /fss/v1/clients/{name} with {"expiresAt":"2027-06-30T00:00:00Z"} to set a date, or {"expiresAt":null} to remove it. Keys you leave out are kept, and the token does not change.

An expired client gets 401. Extending its expiry brings the same token back, so scripts need no change. For clients you rotate on a schedule, prefer an expiry, so a forgotten client stops by itself. Rotation does not move the expiry: extend it when you rotate.

Revoke a client

  1. In the API Clients window, select the client and click Revoke....
  2. Confirm in the Revoke API Client dialog.

Over the API, send DELETE /fss/v1/clients/{name}. It answers 200 with {"name":"<name>","revoked":true}; an unknown or already revoked name gets 404.

The token stops at once on every node. The client stays listed as Revoked for the record. Its name can be given to a new client; the revoked one is then kept under <name>~revoked-<time>.

Verify

  1. In the API Clients window, check the client's Status and Expires.
  2. Call GET /fss/v1/info with the old token (401 after a rotation or revocation) and with the new token (200).

Troubleshooting

401 right after a rotation

A script still sends the old token. Roll out the new one; rotation takes effect immediately.

409 on a rotation

The call reached the standby node. Retry through the load balancer or call the leader.

Next steps