Sign in

v33

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-05-28103497709.6 KB
Embedded Wallet Auth

Verify an authentication credential

Complete the verification step for a previously created authentication credential and issue a session signing key.

For EMAIL_OTP credentials, supply the one-time password that was emailed to the user along with a client-generated public key. For OAUTH credentials, supply a fresh OIDC token (iat must be less than 60 seconds before the request) along with the client-generated public key; this is also the reauthentication path after a prior session expired. The token identity (iss, aud, and sub) must match the OAuth credential being verified. In sandbox, the token's nonce must equal sha256(clientPublicKey). For PASSKEY credentials, the client completes a WebAuthn assertion (navigator.credentials.get()) against the Grid-issued challenge returned from POST /auth/credentials/{id}/challenge, and submits the resulting assertion with the Request-Id header. The clientPublicKey for PASSKEY credentials is supplied on the challenge call, where it is bound into the pending session-creation request.

On success, the response contains an encryptedSessionSigningKey that is encrypted to the supplied clientPublicKey, along with an expiresAt timestamp marking when the session expires. The clientPublicKey is ephemeral and one-time-use per verification request.

post/auth/credentials/{id}/verify

Path parameters

idstring required

The id of the authentication credential to verify (the id field of the AuthMethod returned from POST /auth/credentials).

Headers

Request-Idstring

The requestId returned alongside the Grid-issued challenge from POST /auth/credentials/{id}/challenge, echoed back exactly here so Grid can correlate the assertion with the pending challenge.

Request body

OR
OR

Example request

{
  "otp": "123456",
  "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
}

Response

Authentication credential verified and session issued

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