Skip to main content
POST
cURL

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

clientPublicKey
string
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.

Pattern: ^(0[23][0-9a-fA-F]{64}|04[0-9a-fA-F]{128})$
Example:

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

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.
  • SMS_OTP: A one-time password delivered to the user's phone number.
  • PASSKEY: A WebAuthn passkey bound to the user's device.
Available options:
OAUTH,
EMAIL_OTP,
SMS_OTP,
PASSKEY
nickname
string
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.

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 session signing key 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
deprecated

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

Example:

"w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf"