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:
-
Call
POST /auth/sessions/{id}/refreshwith the request body{ "clientPublicKey": "02..." }and no signature headers. Send a freshly generated client public key and retain its private key. Grid binds the suppliedclientPublicKeyinto the session-refresh payload, persists it as a pending request, and returns202withpayloadToSign,requestId, andexpiresAt. -
Sign
payloadToSignwith the current session signing key, then retry the same request with the full API-key stamp asGrid-Wallet-Signature, therequestIdechoed back asRequest-Id, and the sameclientPublicKeyin the request body. On success, Grid returns a newAuthSession. Sending a compressedclientPublicKeyselects 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 asencryptedSessionSigningKey.
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.
Authorizations
API token authentication using format <api token id>:<api client secret>
Headers
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.
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.
Path Parameters
The id of the active session to refresh.
Body
Request body for refreshing an active authentication session. The clientPublicKey is required on both steps of the signed-retry flow and must match on both. Its SEC1 encoding selects how the refreshed session signing key is delivered: a compressed key gets the recommended client-held-key model, where the client retains the new signing key itself; an uncompressed key gets the deprecated legacy flow, where Grid returns the new key as encryptedSessionSigningKey sealed to it. On the initial call, Grid binds the supplied key into the session-creation payload returned as payloadToSign.
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.
^(0[23][0-9a-fA-F]{64}|04[0-9a-fA-F]{128})$"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.
200 response returned by an Embedded Wallet operation that the wallet provider has accepted but not yet settled — a consensus- or approval-gated activity that is still in flight. It is not an error and needs no client action beyond patience: the backend reconciles the operation to its terminal state on its own. The client MAY re-send the byte-identical request to converge sooner; the request is idempotent and returns the settled success response once the operation completes.
Always PROCESSING. Marks a still-in-flight operation whose terminal result is not yet available.
PROCESSING "PROCESSING"
Human-readable explanation that the operation is still being processed and the same request may be retried.
"This login is still being processed. Retry the same request in a moment."