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 it as a compressed P-256 key in lowercase hex (66 characters, 02 or 03 prefix). The client keeps the matching private key as the resulting session signing key. An uppercase or uncompressed key is rejected with 400 INVALID_INPUT. 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; that body is returned as payloadToSign so the client can check what the passkey authorizes before signing. 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.
Authorizations
API token authentication using format <api token id>:<api client secret>
Path Parameters
The id of the authentication credential to re-challenge (the id field of the AuthMethod returned from POST /auth/credentials).
Body
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.
Required for PASSKEY credentials. Client-generated P-256 public key as a compressed SEC1 point in lowercase hex: 66 characters, a 02 or 03 prefix followed by the 32-byte X coordinate. The client keeps the matching private key as the session signing key. An uppercase or uncompressed key is rejected with 400 INVALID_INPUT. Grid bakes this public key into the session-creation payload that the returned challenge is computed from. Ignored for EMAIL_OTP and SMS_OTP.
66^0[23][0-9a-f]{64}$"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.
System-generated unique identifier for the authentication credential.
"AuthMethod:019542f5-b3e7-1d02-0000-000000000001"
Identifier of the internal account that this credential authenticates.
"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
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.
OAUTH, EMAIL_OTP, SMS_OTP, PASSKEY 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@lightspark.com"
Creation timestamp.
"2026-04-08T15:30:01Z"
Last update timestamp.
"2026-04-08T15:35:00Z"
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.
"KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew"
The platform's reference for the administrator this credential belongs to, for a credential added with POST /auth/admin-credentials. Absent for the account owner's credentials.
"member_8f2c1a"
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.
"{\"version\":\"v1.0.0\",\"data\":\"7b227461726765745075626c6963...\",\"dataSignature\":\"30450221...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"