Start a device-code CLI authorization

POST

/v1/auth/cli/device

const url = 'https://api.aetherpush.com/v1/auth/cli/device';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"deviceId":"example","deviceName":"Ubuntu ThinkBook","clientName":"example","clientVersion":"example","clientPlatform":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aetherpush.com/v1/auth/cli/device \
  --header 'Content-Type: application/json' \
  --data '{ "deviceId": "example", "deviceName": "Ubuntu ThinkBook", "clientName": "example", "clientVersion": "example", "clientPlatform": "example" }'

The fallback for machines that cannot open a browser or bind a loopback port: SSH sessions, containers, locked-down hosts. The CLI prints the user code and polls POST /v1/auth/cli/token with grantType: device_code.

The user code is short by design, so it is protected by a 10-minute expiry and strict rate limiting on the activation endpoint rather than by entropy.

Parameters

Header Parameters

X-Aether-CLI-Version

string

Client version, used when the body omits clientVersion.

Request Body

application/json

object

deviceId

string

deviceName

string

clientName

string

clientVersion

string

clientPlatform

string

Responses

201

Device authorization created.

application/json

RFC 8628 device authorization response. Field names follow the RFC, not the rest of this API.

object

device_code

required

High-entropy secret the CLI polls with. Never shown to the user.

string

user_code

required

Short code the user types into the activation page.

string

verification_uri

required

string

verification_uri_complete

required

string

expires_in

required

Seconds until the request expires.

integer

interval

required

Minimum seconds between polls. Polling faster earns a slow_down response.

integer

Example

{
  "user_code": "K27P-B744",
  "verification_uri": "https://dashboard.aetherpush.com/activate",
  "verification_uri_complete": "https://dashboard.aetherpush.com/activate?user_code=K27P-B744",
  "expires_in": 600,
  "interval": 5
}

429

Too many authorization requests from this address.

application/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.

application/json

Error

object

error

required

Human-readable error message.

string

code

required

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