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

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.

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