Sign in
Embedded Wallet Auth

Refresh an authentication session

Refresh an active Embedded Wallet auth session and create a new session signing key. Session refresh is a two-step signed-retry flow:

  1. Call POST /auth/sessions/{id}/refresh with the request body { "clientPublicKey": "02..." } and no signature headers. Send a freshly generated client public key and retain its private key. Grid binds the supplied clientPublicKey into the session-refresh payload, persists it as a pending request, and returns 202 with payloadToSign, requestId, and expiresAt.

  2. Sign payloadToSign with the current session signing key, then retry the same request with the full API-key stamp as Grid-Wallet-Signature, the requestId echoed back as Request-Id, and the same clientPublicKey in the request body. On success, Grid returns a new AuthSession. Sending a compressed clientPublicKey selects the recommended client-held-key model, where the client retains the new session signing key and no key material is returned; sending an uncompressed key selects the deprecated legacy flow, where the new key is sealed to it and returned as encryptedSessionSigningKey.

The original session must still be active on both steps so it can authorize the refresh. If the session has already expired, use the credential reauthentication flow instead.

post/auth/sessions/{id}/refresh

Path parameters

idstring required

The id of the active session to refresh.

Headers

Grid-Wallet-Signaturestring

Full API-key stamp built over the prior payloadToSign with the current session API keypair. Required on the signed retry; ignored on the initial call.

Request-Idstring

The requestId returned in the prior 202 response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry; must be paired with Grid-Wallet-Signature.

Request body

clientPublicKeystring required

Client-generated P-256 public key; the matching private key is retained on the client. Send a compressed SEC1 key (02/03 prefix followed by the 32-byte X coordinate; 66 hex characters) for the recommended client-held-key model, where that private key becomes the new session signing key. Send an uncompressed SEC1 key (04 prefix followed by the 32-byte X and 32-byte Y coordinates; 130 hex characters) for the deprecated legacy flow, where Grid seals the new session signing key to it and returns it as encryptedSessionSigningKey on the signed retry.

Example request

{
  "clientPublicKey": "02f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31"
}

Response

The session refresh's underlying wallet-provider activity is still in flight — a WalletOperationProcessing body with status: "PROCESSING". The client re-sends the byte-identical signed retry until it gets the 201; the backend also reconciles the activity to terminal on its own.

status'PROCESSING' required

Always PROCESSING. Marks a still-in-flight operation whose terminal result is not yet available.

messagestring

Human-readable explanation that the operation is still being processed and the same request may be retried.

Example response

{
  "status": "PROCESSING",
  "message": "This login is still being processed. Retry the same request in a moment."
}

Changes