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
New authentication session created successfully.
An authentication session on an Embedded Wallet internal account. Returned from GET /auth/sessions (list) and POST /auth/credentials/{id}/verify (on credential verification) or POST /auth/sessions/{id}/refresh (on mid-session refresh). The clientPublicKey encoding on the issuing request selects the flow: a compressed key gets the client-held-key model, where the client generates and retains the session signing key and session-issuing responses carry no key material; an uncompressed key gets the deprecated legacy flow, where Grid seals the session signing key to that public key and returns it as encryptedSessionSigningKey. Never returned by the list endpoint.
System-generated unique identifier for the session. Pass this value to DELETE /auth/sessions/{id} to revoke the session before expiresAt. Overrides the id inherited from AuthMethod so this response identifies the session rather than the authenticating credential.
"Session:019542f5-b3e7-1d02-0000-000000000003"
Identifier of the internal account that this credential authenticates.
"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
The type of authentication credential.
OAUTH: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple.EMAIL_OTP: A one-time password delivered to the user's email address.SMS_OTP: A one-time password delivered to the user's phone number.PASSKEY: A WebAuthn passkey bound to the user's device.
OAUTH, EMAIL_OTP, SMS_OTP, PASSKEY Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for SMS_OTP credentials this is the E.164 phone number; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time.
"example@lightspark.com"
Creation timestamp.
"2026-04-08T15:30:01Z"
Last update timestamp.
"2026-04-08T15:35:00Z"
Timestamp after which the session is no longer valid and the session signing key must not be used to sign further requests.
"2026-04-09T15:30:01Z"
Base64url-encoded WebAuthn credential identifier for this passkey. Present only for PASSKEY authentication credentials. Corresponds to PublicKeyCredential.rawId; pass this value as allowCredentials[].id when requesting a passkey assertion for this auth method.
"KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew"
Deprecated; present only for the legacy flow, selected by sending an uncompressed clientPublicKey on the verification or refresh request. Grid seals the session signing key to that public key and returns it here as a base58check string (a 33-byte compressed P-256 encapsulated public key followed by AES-256-GCM ciphertext) for the client to decrypt with its private key.
The recommended client-held-key flow sends a compressed clientPublicKey instead: the client generates and retains the session signing key itself, so this field is omitted — the same way EMAIL_OTP and SMS_OTP sessions have always worked. See the "Client keys & signing" guide. Always omitted from list responses (GET /auth/sessions).
"w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf"