Skip to content
AetherAether Docs

Complete login with an authenticator code

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

Verifies a six-digit TOTP code for a pending login and, on success, consumes the pending token and issues the session access key. Each code works once; reusing a code within its time window is rejected.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
pendingToken
required
string
code
required

Six-digit code from the authenticator app.

string
Examplegenerated
{
  "pendingToken": "example",
  "code": "example"
}

Responses

Section titled “Responses”

200

Section titled “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

Section titled “400”

Pending token or code missing.

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 or expired, the code is wrong, no authenticator is set up, or the code was already used.

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”

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