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": "04..." } and no signature headers. Grid builds a Turnkey create-read-write-session payload, binds the supplied clientPublicKey into that 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 with an encryptedSessionSigningKey sealed to that client public key.

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

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/auth/sessions/{id}/refresh \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
}
'

201

{
  "id": "Session:019542f5-b3e7-1d02-0000-000000000011",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "EMAIL_OTP",
  "encryptedSessionSigningKey": "w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf",
  "nickname": "[e-mail]",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z",
  "expiresAt": "2026-04-08T15:50:00Z"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature · string

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-Id · string

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

id · string · required

The id of the active session to refresh.

Body

application/json

Request body for refreshing an active authentication session. The clientPublicKey is required on both steps of the signed-retry flow. On the initial call, Grid binds this key into the Turnkey session-creation payload returned as payloadToSign; on the signed retry, the client echoes the same key back and Grid uses it to encrypt the newly issued session signing key.

clientPublicKey · string · required

Client-generated P-256 public key, hex-encoded in uncompressed SEC1 format (04 prefix followed by the 32-byte X and 32-byte Y coordinates; 130 hex characters total). The matching private key must remain on the client. Grid binds this key into the session-creation payload on the initial call and seals the returned encryptedSessionSigningKey to it on the signed retry.

Pattern: ^04[0-9a-fA-F]{128}$

Example:

"04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"

Response

201

application/json

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). Only session-issuing responses include encryptedSessionSigningKey — it is delivered exactly once at the moment the session is issued and is never returned by the list endpoint.

id · string · 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.

Example:

"Session:019542f5-b3e7-1d02-0000-000000000003"

accountId · string · required

Identifier of the internal account that this credential authenticates.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

type · enum<string> · 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.
• PASSKEY: A WebAuthn passkey bound to the user's device.

Available options: OAUTH, EMAIL_OTP, PASSKEY

nickname · string · required

Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; 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:

"[e-mail]"

createdAt · string<date-time> · required

Creation timestamp.

Example:

"2026-04-08T15:30:01Z"

updatedAt · string<date-time> · required

Last update timestamp.

Example:

"2026-04-08T15:35:00Z"

expiresAt · string<date-time> · required

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

Example:

"2026-04-09T15:30:01Z"

credentialId · string

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.

Example:

"KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew"

encryptedSessionSigningKey · string

HPKE-encrypted session signing key, sealed to the clientPublicKey supplied on the verification or refresh request. Encoded as a base58check string: the decoded payload is a 33-byte compressed P-256 encapsulated public key followed by AES-256-GCM ciphertext. The client decrypts this key with its private key and uses it to sign subsequent Embedded Wallet requests until expiresAt.

Only returned from session-issuing responses like POST /auth/credentials/{id}/verify and POST /auth/sessions/{id}/refresh. Omitted from responses that simply surface existing sessions (e.g. GET /auth/sessions) — Grid does not retain the plaintext key after the client has decrypted it.

Example:

"w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf"