Complete a passwordless passkey sign-in

POST

/v1/auth/passkey/login

curl --request POST \
  --url https://api.aetherpush.com/v1/auth/passkey/login \
  --header 'Content-Type: application/json' \
  --data '{ "response": {} }'

• Production
• Staging
• Local development

Verifies a discoverable-credential assertion and issues the session access key. The credential is resolved globally by its id, the asserted userHandle must match the credential’s owner, and user verification is required.

Request Body^required

Media typeapplication/json

object

response

required

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

object

key

additional properties

any

Example^generated

{
  "response": {}
}

Responses

200

Signed in. 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 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

Unknown challenge or credential, or the assertion failed.

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

403

The account’s email address is not verified.

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