Start a browser CLI authorization (loopback + PKCE)

POST

/v1/auth/cli/authorizations

curl --request POST \
  --url https://api.aetherpush.com/v1/auth/cli/authorizations \
  --header 'Content-Type: application/json' \
  --data '{ "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "codeChallengeMethod": "S256", "redirectUri": "http://127.0.0.1:49152/callback", "state": "u8Kq3rN1sVx2", "deviceId": "0f8c2a1e-9f1a-4b2c-8d3e-5a6b7c8d9e0f", "deviceName": "Adrian'\''s MacBook Pro", "clientName": "aether-cli", "clientVersion": "0.5.0", "clientPlatform": "darwin-arm64" }'

• Production

Opens a ceremony for a CLI that can bind a local loopback listener. The response carries a dashboard URL for the CLI to open; the browser completes whatever authentication the account requires, including MFA.

The request expires in 10 minutes. Rate limited to 20 requests per 10 minutes per address.

Parameters

Header Parameters

X-Aether-CLI-Version

string

Client version, used when the body omits clientVersion.

Request Body^required

Media typeapplication/json

object

codeChallenge

required

Base64url S256 challenge derived from the CLI’s code verifier.

string

codeChallengeMethod

required

Only S256 is accepted.

string

Allowed values: S256

redirectUri

required

Loopback callback the browser is sent to after approval. Must use http on the literal address 127.0.0.1 or [::1], with no credentials, fragment, or query string. Any other target is rejected: whoever receives this URL receives the authorization code.

string

state

Opaque value echoed back on the redirect so the CLI can detect a swapped response.

string

deviceId

string

deviceName

string

clientName

string

clientVersion

string

clientPlatform

string

Responses

201

Ceremony created.

Media typeapplication/json

object

authorizationId

required

string format: uuid

authorizeUrl

required

Dashboard page the CLI opens in the browser.

string

expiresAt

required

Unix timestamp in milliseconds.

integer format: int64

Example

{
  "authorizationId": "11111111-2222-3333-4444-555555555555",
  "authorizeUrl": "https://dashboard.aetherpush.com/cli/authorize?request=11111111-2222-3333-4444-555555555555",
  "expiresAt": 1786866445538
}

400

Invalid challenge, challenge method, redirect URI, or state.

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 authorization requests from this address.

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

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