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

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

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

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