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
• Staging
• Local development

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

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

The bearer token is missing, invalid, or expired.

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

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

One of:

object

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

object

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, or run the CLI device ceremony. Endpoints that enforce both guards reject API keys and named access keys earlier with a plain 403 response and no code. 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": "The requested resource was not found.",
  "requestId": "req_abc123"
}

404

No pending request matches that code.

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

Too many activation attempts.

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

500

Internal server error.

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