Skip to content
AetherAether Docs

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

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 Bodyrequired

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

One of the recovery codes shown when they were generated.

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
string
expires
required
integer format: int64
remainingCodes
required

Unused recovery codes left after consuming this one.

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

400

Section titled “400”

Pending token or recovery 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 the recovery code is wrong or 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"
}