Sign in

v33

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-05-28103497709.6 KB
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": "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

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

Example request

{
  "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
}

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' | '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.
  • 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 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

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.

expiresAtstring date-time required

Timestamp after which the session is no longer valid and the encryptedSessionSigningKey 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"
}