Embedded Wallet Auth

Refresh an authentication session

Changed on

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 P-256 public key as a compressed key in lowercase hex (66 characters, 02 or 03 prefix) 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. The client keeps the private key matching clientPublicKey as the new session signing key, and no key material is returned. An uppercase or uncompressed key is rejected with 400 INVALID_INPUT.

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 as a compressed SEC1 point in lowercase hex: 66 characters, a 02 or 03 prefix followed by the 32-byte X coordinate. The client keeps the matching private key as the new session signing key. An uppercase or uncompressed key is rejected with 400 INVALID_INPUT.

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

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • warning

      added the new EXACT_AMOUNT_UNAVAILABLE enum value to the response property for the response status