Skip to content
AetherAether Docs

Start passkey authentication for a pending login

POST
/v1/auth/mfa/challenge
curl --request POST \
  --url https://api.aetherpush.com/v1/auth/mfa/challenge \
  --header 'Content-Type: application/json' \
  --data '{ "pendingToken": "example" }'

Exchanges a pending login token (from a mfaRequired login response) for WebAuthn authentication options. Each call invalidates any prior unconsumed authentication challenge for the account. Does not count against the pending login’s five-attempt budget; only verification calls do. Rate limited like login: 5 failed attempts per client address per 15 minutes.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
pendingToken
required
string
Examplegenerated
{
  "pendingToken": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

WebAuthn authentication options to pass to the browser.

Media typeapplication/json
object
options
required

WebAuthn PublicKeyCredentialRequestOptionsJSON, as produced by SimpleWebAuthn’s generateAuthenticationOptions(). Pass it to startAuthentication() from @simplewebauthn/browser.

object
key
additional properties
any
Examplegenerated
{
  "options": {}
}

400

Section titled “400”

Pending token missing, or the account has no passkeys.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

401

Section titled “401”

The pending login is invalid, consumed, or expired.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

429

Section titled “429”

Too many MFA attempts.

Media typeapplication/json

Returned with HTTP 429 when an endpoint-specific rate limit is hit. retryAfterSeconds indicates how long the client should wait before retrying.

object
error
required
string
retryAfterSeconds
integer
>= 1
requestId
string
Example
{
  "error": "Too many login attempts. Please try again later.",
  "retryAfterSeconds": 900,
  "requestId": "req_abc123"
}

503

Section titled “503”

Passkeys are not configured on this server.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}