Start a step-up assertion challenge
const url = 'https://api.aetherpush.com/v1/mfa/stepup/challenge';const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aetherpush.com/v1/mfa/stepup/challenge \ --header 'Authorization: Bearer <token>'Dashboard sessions only. Returns WebAuthn authentication options for the
account’s own passkeys, to prove possession of an existing factor before
changing the factor set. Opening a challenge voids the account’s
in-flight one. API keys and named access keys are rejected by the login
session guard with a plain 403. A valid CLI session or a session that
predates credential attribution is refused with 403 and code
dashboard_session_required; a TOTP proof needs no challenge and stays
available to any login session. Accounts with only an authenticator app
receive 409 and step up with a TOTP code instead.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”WebAuthn authentication options for the step-up assertion.
object
WebAuthn PublicKeyCredentialRequestOptionsJSON for the step-up assertion.
object
Example generated
{ "options": {}}Authentication required.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}API keys and named access keys receive a plain 403. A login session
that is not a dashboard login session receives code
dashboard_session_required.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Returned after login-session validation when a valid session that is
not a dashboard login session tries to issue or widen an API key,
create an access key or change its lifetime, enrol a passkey or
authenticator app, start a passkey step-up challenge, run the CLI
device ceremony, change the password, or request or cancel the
account’s deletion. Endpoints that enforce both guards reject API keys and
named access keys earlier with a plain 403 carrying
code: session_required. API-key creation applies only the
dashboard-session guard, so any non-dashboard credential receives
this response there. Listing,
renaming and revoking stay open to any login session. Sessions created
before the credential_origin column existed cannot be attributed to
the dashboard and are also refused; signing out and back in fixes that.
object
Example
{ "error": "This operation requires a login session. API keys and named access keys cannot access it.", "code": "session_required", "requestId": "req_abc123"}No passkey is available to challenge (code: step_up_unavailable); use a TOTP code.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Returned by the step-up challenge when the account has no passkey to assert; the client falls back to an authenticator code.
object
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}The tenant’s per-minute management API budget is spent.
Retry-After and X-RateLimit-* say when to retry. This is
not a plan quota: quota 429s use the Error envelope and do
not set Retry-After.
Returned with HTTP 429 when an endpoint-specific rate limit is hit,
including the per-tenant management API budget. Not the process-wide
address limiter (see GlobalAddressRateLimitErrorResponse).
retryAfterSeconds
indicates how long the client should wait before retrying, and matches
the Retry-After header when that header is set. code names the
limit that fired so clients can translate without matching on error.
object
Example
{ "error": "Rate limit exceeded", "code": "tenant_rate_limit_exceeded", "retryAfterSeconds": 60}Headers
Section titled “Headers”Seconds until the tenant window resets.