Sign in
Backend Wallets

Rotate wallet secret.

Changed on

Rotate wallet secret (authentication key).

Replaces the current wallet secret (ECDSA P-256 public key) used for X-Wallet-Auth JWT signing. The old secret will be marked as "rotated" and immediately becomes unusable (no grace period).

Uses provided-key authentication: the request must include a walletAuthToken JWT signed by the private key corresponding to the NEW publicKey being registered. This proves possession of the new private key without transmitting it.

Requires an AAL2 session (MFA step-up). Users must enroll MFA and complete step-up authentication before calling this endpoint.

post/v2/accounts/backend/rotate-secrets

Request

  • Base URL: https://api.openfort.io
  • URL: https://api.openfort.io/v2/accounts/backend/rotate-secrets
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Request body

newPublicKeystring required

New ECDSA P-256 public key for wallet authentication (PEM format). This will replace the current wallet secret used for X-Wallet-Auth JWT signing.

walletAuthTokenstring required

JWT signed with the private key corresponding to newPublicKey. This proves possession of the private key without transmitting it.

JWT must include: uris (matching request path), reqHash (SHA-256 of request body), iat (issued at), nbf (not before), and optionally exp (expiration).

newKeyIdstring

Key identifier for the new secret. Used to identify this key in X-Wallet-Auth JWT headers.

Example request

{
  "newPublicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
  "walletAuthToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "newKeyId": "ws_1234567890"
}

Response

Successful response.

object'walletSecretRotation' required

The type of object.

successboolean required

Whether the rotation was successful.

rotatedAtinteger required

Timestamp when the rotation occurred (Unix epoch seconds).

Changes

  • 88be7ccfca19Revision changes
    • info

      the endpoint scheme security sk was added to the API

    • info

      added the non-success response with the status

  • 63216e0be364Revision changes
    • breaking

      added the new required request property

    • breaking

      added the new required request property

    • warning

      removed the request property

    • info

      the endpoint scheme security user_project was added to the API

    • info

      the endpoint scheme security wallet_auth was removed from the API