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

{
  "id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "EMAIL_OTP",
  "nickname": "example@lightspark.com",
  "otpEncryptionTargetBundle": "'{version:v1.0.0,data:7b227461726765745075626c6963...,dataSignature:30450221...,enclaveQuorumPublic:04a1b2c3...}'",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z"
}

Embedded Wallet Auth

Re-issue an authentication credential challenge

Re-issue the challenge for an existing authentication credential.

For EMAIL_OTP and SMS_OTP credentials, this triggers a new one-time password to the contact on file and returns a fresh otpEncryptionTargetBundle for the client to HPKE-encrypt the OTP attempt against. After the user receives the new OTP, build the encryptedOtpBundle under the new target bundle and call POST /auth/credentials/{id}/verify to begin the secure OTP login flow.

OAUTH credentials do not have a challenge step. To authenticate or reauthenticate an OAuth credential, call POST /auth/credentials/{id}/verify with a fresh OIDC token and a clientPublicKey.

For PASSKEY credentials, this issues a fresh Grid reauthentication challenge. The request body must carry the client’s ephemeral clientPublicKey so Grid can bake it into the session-creation payload the returned challenge is computed from — send a compressed key for the recommended client-held-key model, where the client retains the matching private key as the resulting session signing key, or an uncompressed key for the deprecated legacy flow. The response is a PasskeyAuthChallenge — the passkey auth method fields plus the WebAuthn credentialId, new challenge, requestId, and expiresAt. The challenge value is the lowercase hex-encoded SHA-256 digest of the canonical session-creation body, not a base64url string. The client base64url-decodes credentialId for allowCredentials[].id and UTF-8 encodes challenge (for example, new TextEncoder().encode(challenge)) as the WebAuthn challenge in navigator.credentials.get(), then submits the resulting assertion to POST /auth/credentials/{id}/verify with Request-Id: <requestId> to receive a session.

POST

auth

credentials

{id}

challenge

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

{
  "id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "EMAIL_OTP",
  "nickname": "example@lightspark.com",
  "otpEncryptionTargetBundle": "'{version:v1.0.0,data:7b227461726765745075626c6963...,dataSignature:30450221...,enclaveQuorumPublic:04a1b2c3...}'",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

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

Body

application/json

Request body. Required when re-challenging a PASSKEY credential (must carry clientPublicKey). Ignored for EMAIL_OTP and SMS_OTP, where the credential type alone is sufficient — the OTP is delivered out-of-band. OAuth credentials do not use this endpoint.

Request body for POST /auth/credentials/{id}/challenge. Required when re-challenging a PASSKEY credential — must carry clientPublicKey so Grid can bake it into the session-creation payload the returned challenge is computed from. Ignored for EMAIL_OTP and SMS_OTP, where the credential type alone is sufficient because the OTP is delivered out-of-band. OAuth credentials do not use this endpoint; authenticate or reauthenticate them with POST /auth/credentials/{id}/verify.

clientPublicKey

string

Required for PASSKEY credentials; 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 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 session signing key to it instead. Grid bakes this public key into the session-creation payload that the returned challenge is computed from. Ignored for EMAIL_OTP and SMS_OTP.

Required string length: 66 - 130

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

Example:

"02f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31"

Response

Challenge re-issued for the authentication credential. For EMAIL_OTP and SMS_OTP the body is a plain AuthMethod and a new OTP has been sent. For PASSKEY the body is a PasskeyAuthChallenge carrying the passkey credentialId, freshly issued challenge, requestId, and expiresAt required to complete reauthentication via POST /auth/credentials/{id}/verify. When the OTP send's underlying wallet-provider activity is still in flight, the body is instead a WalletOperationProcessing carrying a PROCESSING status — re-request the challenge until the send settles; the backend also reconciles it to terminal on its own.

Auth Method Response
Passkey Auth Challenge
Wallet Operation Processing

Strict wrapper around AuthMethod. Used directly as the registration response on POST /auth/credentials and inside AuthCredentialResponseOneOf for the EMAIL_OTP / SMS_OTP branches of POST /auth/credentials/{id}/challenge. The only difference from AuthMethod is unevaluatedProperties: false, which disambiguates the oneOf against PasskeyAuthChallenge — without the strictness, an AuthMethod with extra fields would ambiguously match both branches.

For EMAIL_OTP and SMS_OTP credentials, responses that initiate or reissue an OTP challenge carry otpEncryptionTargetBundle so the client can HPKE-encrypt the OTP code in the subsequent POST /auth/credentials/{id}/verify call without the plaintext code ever transiting the server. First-time EMAIL_OTP wallet bootstrap registration can omit it; call POST /auth/credentials/{id}/challenge if it is absent.

string

required

System-generated unique identifier for the authentication credential.

Example:

"AuthMethod:019542f5-b3e7-1d02-0000-000000000001"

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"

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"

otpEncryptionTargetBundle

string

HPKE encryption target bundle for a freshly initiated OTP challenge. Returned only on EMAIL_OTP and SMS_OTP responses that initiate or reissue an OTP challenge, such as POST /auth/credentials/{id}/challenge and signed-retry add responses. It is omitted from first-time EMAIL_OTP wallet bootstrap registration; call POST /auth/credentials/{id}/challenge for the new credential if it is absent. The client generates an ephemeral P-256 keypair (the Target Encryption Key, or TEK) and uses this bundle as the recipient when HPKE-encrypting {otp_code, public_key}, where public_key is the compressed TEK public key; the encrypted payload is submitted as encryptedOtpBundle on POST /auth/credentials/{id}/verify. The bundle is one-time-use per OTP issuance — re-issue via POST /auth/credentials/{id}/challenge to obtain a fresh bundle. The matching TEK private key must remain on the client and is used to stamp the exact UTF-8 bytes of the payloadToSign string returned by the first verify call. Preserve that string unchanged on the signed retry. Treat the bundle as opaque and pass it to your HPKE library; the Global Accounts client-keys guide shows how.

Example:

"{\"version\":\"v1.0.0\",\"data\":\"7b227461726765745075626c6963...\",\"dataSignature\":\"30450221...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"

Using the API

API documentation

Re-issue an authentication credential challenge

Authorizations

Path Parameters

Body

Response