Sign in
latestOpenAPI 3.1.0Proprietary2026-08-201536391.5 MB

4f1f6b937f93

Embedded Wallet Auth

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:

  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.

post/auth/sessions/{id}/refresh

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

New authentication session created successfully.

idstring required

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.

accountIdstring required

Identifier of the internal account that this credential authenticates.

type'OAUTH' | 'EMAIL_OTP' | 'SMS_OTP' | 'PASSKEY' required

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.
credentialIdstring

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.

nicknamestring required

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.

createdAtstring date-time required

Creation timestamp.

updatedAtstring date-time required

Last update timestamp.

encryptedSessionSigningKeystring

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).

expiresAtstring date-time required

Timestamp after which the session is no longer valid and the session signing key must not be used to sign further requests.

Example response

{
  "id": "Session:019542f5-b3e7-1d02-0000-000000000003",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "credentialId": "KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew",
  "nickname": "example@lightspark.com",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z",
  "encryptedSessionSigningKey": "w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf",
  "expiresAt": "2026-04-09T15:30:01Z"
}