Resolve a printed activation code

POST

/v1/cli/activate

curl --request POST \
  --url https://api.aetherpush.com/v1/cli/activate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "userCode": "K27P-B744" }'

• Production

Turns the code the CLI printed into an authorization request the user can approve. API keys and named access keys receive a plain 403. The endpoint is rate limited per account and address because the code is deliberately short. Every miss answers the same 404 regardless of why.

Authorizations

• accessKeyAuth

Request Body^required

Media typeapplication/json

object

userCode

required

The code printed by the CLI. Case, spacing and dashes are ignored.

string

Responses

200

Request metadata for the approval screen.

Media typeapplication/json

Everything the approval screen needs and nothing more. Codes, challenges, state and the redirect target are never returned.

object

authorizationId

required

string format: uuid

mode

required

string

Allowed values: pkce device

deviceName

string | null

clientName

string | null

clientVersion

string | null

clientPlatform

string | null

requestIp

Address the ceremony was started from, so the user can tell whether it was them.

string | null

expiresAt

required

integer format: int64

stepUpRequired

required

True when the account has MFA and the current dashboard session is too old to authorize a new device. The page should send the user back through sign-in before offering the approve action.

boolean

mfaSetupOverdue

True when the account passed its two-factor setup deadline without enrolling. Approving is refused in that state, so the page should offer enrollment instead of the approve action.

boolean

Example

{
  "mode": "pkce"
}

400

Missing or oversized code.

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 bearer token is missing, invalid, or expired.

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

403

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.

Media typeapplication/json

Any of:

Error

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

DashboardSessionRequiredError

DashboardSessionRequiredError

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

error

required

string

code

required

string

Allowed values: dashboard_session_required

requestId

string

Example

{
  "error": "This operation requires a login session. API keys and named access keys cannot access it.",
  "code": "session_required",
  "requestId": "req_abc123"
}

404

No pending request matches that code.

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

Two causes share this status. Too many activation attempts from this address, or the tenant’s per-minute management API budget is spent. The tenant limiter answers RateLimitErrorResponse (error, retryAfterSeconds) with Retry-After.

Media typeapplication/json

One of:

Error

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

RateLimitError

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": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

Headers

Retry-After

integer

>= 1

Present for the tenant limiter.

500

Internal server error.

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