--- title: "Refresh an authentication session" method: POST path: "/auth/sessions/{id}/refresh" tags: ["Embedded Wallet Auth"] --- # Refresh an authentication session `POST /auth/sessions/{id}/refresh` 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. ## Path parameters - `id` string, required ## Headers - `Grid-Wallet-Signature` string - `Request-Id` string ## Request body - AuthSessionRefreshRequest — 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`. - `clientPublicKey` string, 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. ## Response `200` 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. - WalletOperationProcessing — `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. - `status` 'PROCESSING', required — Always `PROCESSING`. Marks a still-in-flight operation whose terminal result is not yet available. - `message` string — Human-readable explanation that the operation is still being processed and the same request may be retried. ## Other responses - `201` — New authentication session created successfully. - `202` — Challenge issued. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the current session API keypair, then echo `requestId` on the signed retry. - `400` — Bad request - `401` — Unauthorized. Returned when the `BasicAuth` credentials are missing or invalid, when the target session is no longer active and cannot be used for refresh, when the signed retry omits `Grid-Wallet-Signature`, when the provided signature is malformed or does not match the pending refresh challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry's `clientPublicKey` does not match the one bound into `payloadToSign` on the initial call. - `404` — Session not found - `500` — Internal service error ## Changes - **2026-08-25** `8964d9c7b6f9` — 1 info - added the success response with the status `200` - **2026-08-20** `4f1f6b937f93` — 1 warning, 1 info - changed the pattern of the request property `clientPublicKey` from `^04[0-9a-fA-F]{128}$` to `^(0[23][0-9a-fA-F]{64}|04[0-9a-fA-F]{128})$` - response property `allOf[subschema #2]/encryptedSessionSigningKey` deprecated - **2026-08-14** `aaa1fb8782c8` — 1 warning - added the new `EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED` enum value to the `code` response property for the response status `400` - **2026-08-13** `df12ec487f0e` — 1 warning - added the new `TRANSACTION_SIZE_LIMIT_EXCEEDED` enum value to the `code` response property for the response status `400` - **2026-08-11** `b06902b6595a` — 1 warning - added the new `CARDHOLDER_KYC_NOT_APPROVED` enum value to the `code` response property for the response status `400` [Full history](https://skmtc.dev/stainless-api/apis/grid-api/changes/auth/sessions/:id/refresh/post.md) --- [API](https://skmtc.dev/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/2ec84c06fbec/schema)