Start a sign-in

POST/auth/device

Starts a browser sign-in and returns the codes to show and poll with. It is the first half of the sign-in behind chartnaut login: the person approves in Chartnaut, and Poll a sign-in hands your program a new API key.

Scope	Heavy call	Long poll	CLI
None, no key	No	No	`chartnaut login`

Guidance

The flow: call this, show the person user_code and open verification_uri_complete in their browser, then call Poll a sign-in every interval seconds until it answers 200 with the key.
Ask the person to check that the code on the approval page matches the one you showed. Anyone who approves a code they did not start signs that program in to their account.
The sign-in lasts expires_in seconds, 600. After that, start a new one.
client_name names the machine on the approval page and in the key's name, so the person can recognise and revoke it later on the Developers page.
It takes no key and does not count toward any account's requests a minute. It is limited to 30 calls a minute from one IP address.
A 503 busy means browser sign-in is unavailable. Make a key on the Developers page instead.

Request body

Optional. Up to 4 KB; a body that is not JSON is treated as empty.

Field	Type	Required	Description
`client_name`	string	No	Names the machine. Shown on the approval page and in the new key's name. Control characters are removed, it is cut to 60 characters, and an empty one becomes unknown machine

Response

200 with:

Field	Type	Description
`device_code`	string	64 hex characters. Keep it secret; poll with it
`user_code`	string	Eight letters in two groups, such as `KMPR-TVXZ`, for the person to check. It uses no vowels and no letters that look like digits
`verification_uri`	string	The approval page, `https://terminal.chartnaut.com/morpheus/cli-auth`
`verification_uri_complete`	string	The approval page with the code filled in. Open this one
`expires_in`	integer	Seconds until the sign-in expires: 600
`interval`	integer	Seconds to wait between polls: 3

Status codes

Status	Code	Meaning
`200`	-	The sign-in started
`429`	`rate_limited`	More than 30 starts in a minute from your IP address
`503`	`busy`	Browser sign-in is unavailable. Use a key made on the Developers page
`500`	`internal`	The sign-in could not be started. Retry

Example request

curl https://api.chartnaut.com/v1/auth/device \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "studio-mac"
  }'

Example response

200 OK

{
  "device_code": "9c1e4b7a2d6f08e35a1c7b9d4e2f60a8b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1",
  "user_code": "KMPR-TVXZ",
  "verification_uri": "https://terminal.chartnaut.com/morpheus/cli-auth",
  "verification_uri_complete": "https://terminal.chartnaut.com/morpheus/cli-auth?code=KMPR-TVXZ",
  "expires_in": 600,
  "interval": 3
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Too many sign-in attempts. Wait a minute."
  }
}

From the CLI

chartnaut login

login calls this with the computer's name, prints the code, opens the link, and polls until you click Connect; --no-browser prints the link instead. Sign in walks through it.