Complete login with a recovery code

POST

/v1/auth/mfa/recovery

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

• Production

Consumes one unused recovery code for a pending login and, on success, issues the session access key. Each code works once. The response includes how many codes remain; when it reaches zero, the account owner should regenerate codes from the security settings.

Request Body^required

Media typeapplication/json

object

pendingToken

required

string

code

required

One of the recovery codes shown when they were generated.

string

Example ^generated

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

Responses

200

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

Media typeapplication/json

object

accessKey

required

string

expires

required

integer format: int64

remainingCodes

required

Unused recovery codes left after consuming this one.

integer

Example ^generated

{
  "accessKey": "example",
  "expires": 1,
  "remainingCodes": 1
}

400

Pending token or recovery code missing.

Media typeapplication/json

Error

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

error

required

Human-readable error message.

string

code

required

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.

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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

401

The pending login is invalid or the recovery code is wrong or already used.

Media typeapplication/json

Error

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

error

required

Human-readable error message.

string

code

required

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.

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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

429

Too many MFA attempts.

Media typeapplication/json

RateLimitError

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

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Example

{
  "error": "Too many login attempts. Please try again later.",
  "code": "too_many_login_attempts",
  "retryAfterSeconds": 900,
  "requestId": "req_abc123"
}