Create a pending CLI device session

POST/api/cli/login/sessions

createCliLoginSession

Starts either a browser-mediated CLI login or an SSH-key enrollment. The public-key metadata is parsed and canonicalized by the server before approval.

Authentication is not described for this operation in the spec — that does not mean it is public. Check tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/cli/login/sessions' \
  -H 'Content-Type: application/json' \
  -d '{}'

fetch

fetch("https://neosource.dev/api/cli/login/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

Request bodyrequired

application/json

CreateCliLoginSessionRequest

one of

object
credential_labelrequired
string
example"cli-work-laptop"
machine_namerequired
string
example"Work Laptop"
purposerequired
string
"login"
ssh_key
one of
null
BoundSshKeyRequest
object
namerequired
string
public_keyrequired
string
Complete OpenSSH public-key line. The server parses it and derives the canonical algorithm, fingerprint, and key bytes.
additional propertiesnot allowed
object
expected_account_idrequired
string
Account ID from the existing stored CLI login. The server checks this binding against the browser session before approving the enrollment; it is not a client-only response check.
machine_namerequired
string
example"Work Laptop"
purposerequired
string
"ssh_enrollment"
ssh_keyrequired
BoundSshKeyRequest
object
namerequired
string
public_keyrequired
string
Complete OpenSSH public-key line. The server parses it and derives the canonical algorithm, fingerprint, and key bytes.
additional propertiesnot allowed

Responses

201CLI login session created

application/json

CreateCliLoginSessionResponse

object

approval_urlrequired: string
Browser URL the user opens to approve this login. Key-bearing login and SSH-enrollment URLs add purpose and expiry query hints so a new browser can bridge a mixed-version rollout while old pages continue to ignore them.
device_coderequired: string
The CLI's secret, polled with at the exchange endpoint. Never shown in the browser (RFC 8628 `device_code`).
expires_atrequired: integerint64
interval_secsrequired: integerint64
Suggested seconds between exchange polls (RFC 8628 `interval`).
session_idrequired: string
user_coderequired: string
Short code shown to the user; the browser approval page displays the same value so the user can confirm they match (RFC 8628 `user_code`).

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget