Skip to main content
POST
/
auth
/
sessions
/
{id}
/
refresh
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"
}
'
{
  "id": "Session:019542f5-b3e7-1d02-0000-000000000011",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "EMAIL_OTP",
  "encryptedSessionSigningKey": "w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf",
  "nickname": "example@lightspark.com",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z",
  "expiresAt": "2026-04-08T15:50:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://grid.lightspark.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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:

"example@lightspark.com"

​
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"