Embedded Wallet Auth

Refresh an authentication session

Changed on Sep 15, 2026

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}/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.
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

Request

Base URL: https://api.lightspark.com/grid/2025-10-13
URL: https://api.lightspark.com/grid/2025-10-13/auth/sessions/{id}/refresh
Auth: HTTP basic

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

Sep 15, 20263966e5d38aad Revision changes
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_FUNDS enum value to the response property for the response status
- warning
  added the new NOT_FOUND enum value to the response property for the response status
- warning
  added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status
- warning
  added the new PLATFORM_NOT_FOUND enum value to the response property for the response status
- warning
  added the new QUOTE_EXPIRED enum value to the response property for the response status
- warning
  added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status
- warning
  added the new REQUEST_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SESSION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status
- warning
  added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status
- warning
  added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
Aug 25, 20268964d9c7b6f9 Revision changes
- info
  added the success response with the status

Operation history (8 revisions)