Re-issue an authentication credential challenge

Re-issue the challenge for an existing authentication credential.

For EMAIL_OTP credentials, this triggers a new one-time password email to the address 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-generated WebAuthn challenge for reauthentication. The request body must carry the client’s ephemeral clientPublicKey so Grid can bake it into the Turnkey session-creation payload the returned challenge is computed from — this seals the resulting session signing key to the client. The response is a PasskeyAuthChallenge — the passkey auth method fields plus the WebAuthn credentialId, new challenge, requestId, and expiresAt. The client passes credentialId as allowCredentials[].id and 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

cURL

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": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
}
'

200

emailOtp

{
  "id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "EMAIL_OTP",
  "nickname": "[e-mail]",
  "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

id · 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, 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 Turnkey session-creation payload the returned challenge is computed from. Ignored for EMAIL_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. 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 bakes this key into the Turnkey session-creation payload that the returned challenge is computed from, so the resulting session signing key is sealed to the client. Ignored for EMAIL_OTP.

Required string length: 130

Pattern: ^04[0-9a-fA-F]{128}$

Example:

"04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"

Response

200

application/json

Challenge re-issued for the authentication credential. For EMAIL_OTP the body is a plain AuthMethod and a new OTP email 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.

Auth Method Response

Passkey Auth Challenge

Strict wrapper around AuthMethod. Used directly as the registration response on POST /auth/credentials (all three credential types) and inside AuthCredentialResponseOneOf for the EMAIL_OTP branch 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 credentials, the response also carries 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.

id · 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.
• 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:

"[e-mail]"

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 the freshly initiated OTP challenge. Returned only for EMAIL_OTP credentials. 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}; 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 sign the verificationToken returned on the subsequent 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...\"}"