Complete login with a passkey assertion

POST

/v1/auth/mfa/verify

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

• Production
• Staging
• Local development

Verifies the WebAuthn assertion for a pending login and, on success, consumes the pending token and issues the session access key exactly as a non-MFA login would.

Request Body^required

Media typeapplication/json

object

pendingToken

required

string

response

required

WebAuthn AuthenticationResponseJSON, as returned by startAuthentication() from @simplewebauthn/browser.

object

key

additional properties

any

Example^generated

{
  "pendingToken": "example",
  "response": {}
}

Responses

200

MFA satisfied. Use the returned access key as a Bearer token.

Media typeapplication/json

object

accessKey

required

Raw bearer token. Send as Authorization: Bearer <accessKey> on subsequent requests. Store securely (cookie or secure storage). The server cannot reveal it again.

string

expires

required

Unix timestamp in milliseconds at which this token expires.

integer format: int64

mfaSetupRequired

Present and true when the account has no MFA method yet. Every account is expected to enroll a passkey or an authenticator app. The dashboard nags until mfaSetupDeadline and blocks navigation after it. Clients that cannot enroll (the CLI) may ignore this field.

boolean

mfaSetupDeadline

Unix timestamp in milliseconds. Present alongside mfaSetupRequired; fixed on the account’s first MFA-less login and stable on later logins. Before it, MFA setup is a dismissible prompt; after it, the dashboard requires setup before continuing.

integer format: int64

Example

{
  "accessKey": "abc123-base64url-secret",
  "expires": 1719964800000
}

400

Malformed request or WebAuthn response.

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

The pending login is invalid or expired, the challenge does not match, or the assertion failed verification.

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

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

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