Sign a box in

The three requests behind nucleate login and nucleate logout. A box with no browser asks for a code, waits while its owner approves, and collects a token that can only write.

On this page

The flow #

nucleate login is the OAuth 2.0 device authorization grant (RFC 8628). It suits a box because the box never needs a browser, and its owner never types a secret into a terminal.

  1. The box asks to sign in. It gets two codes: a short one for a person, and a long one it keeps to itself.
  2. The owner approves. They open https://app.nucarium.com/activate on a phone or laptop, sign in to Watch, type the short code, and say which machine this box is.
  3. The box collects its token. It has been polling with the long code. Once the owner approves, the next poll answers with a machine token.

nucleate logout is one more request, which gives the token up.

Three things are different from the ingest requests:

  • No credential is sent. The box has none yet. The client is public: its id is nucleate and there is no client secret.
  • Bodies are form-encoded, as the OAuth standards say, not JSON.
  • Errors are OAuth errors, a JSON object with an error word, not problem documents.

The addresses of these endpoints are also published in the standard place, for a client that discovers them:

GET /.well-known/oauth-authorization-server

Where the sign-in endpoints are (RFC 8414)

Responses #

StatusMeaning
200Authorization server metadata.

1. Ask to sign in #

POST /v1/oauth/device_authorization

The first step of nucleate login (RFC 8628 section 3.1). The box, which has no browser, is given two codes: a user_code for its owner to type into the console, and a device_code it keeps to itself and polls /v1/oauth/token with.

Both codes are single use and last 15 minutes. Watch stores only their hashes.

The client is public: there is no client secret. client_id is nucleate and the only scope is ingest.

Errors are in the OAuth format (OAuthError), not problem details.

Request body #

FieldTypeRequiredMeaning
client_idalways "nucleate"Required
scopealways "ingest"OptionalOptional. ingest is the only scope and the default.
machine_namestringOptionalUnique within the account. No leading or trailing spaces. 1 to 64 characters. Must match ^[^\s\p{Cc}](?:[^\p{Cc}]*[^\s\p{Cc}])?$.

The body is form-encoded (application/x-www-form-urlencoded), not JSON.

POST /v1/oauth/device_authorization
client_id=nucleate&scope=ingest&machine_name=agentbox

Responses #

StatusMeaning
200The codes, and where the owner goes to approve.
400invalid_request (a parameter is missing, repeated or not valid), invalid_client (not nucleate) or invalid_scope (not ingest).
429Too many sign-ins started from one address (slow_down). Wait Retry-After seconds.

The answer:

FieldTypeRequiredMeaning
device_codestringRequiredThe box's secret for this sign-in. Never shown to anyone.
user_codestringRequiredEight letters as XXXX-XXXX, from an alphabet with no vowels and no letters that are easily confused. Must match ^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$.
verification_uristring (uri)Required
verification_uri_completestring (uri)Required
expires_inintegerRequiredSeconds both codes last.
intervalintegerRequiredSeconds the box must leave between polls.

Any field that is not in this table is rejected, and the request with it.

nucleate login prints user_code and verification_uri for the owner, and verification_uri_complete as a link that already carries the code. It keeps device_code in memory and never prints it.

2. The owner approves #

This step happens in the Watch console, with the owner signed in, and is not something a box does. The console looks the code up, shows what is asking, and sends the decision:

The console calls To
GET /v1/device-authorizations/{user_code} Show the owner what is asking to sign in. It answers only while the request is waiting for a decision.
POST /v1/device-authorizations/{user_code}:approve Sign the box in as a machine the account already has, or as a new one with the name given. A new machine counts against the plan's machine limit.
POST /v1/device-authorizations/{user_code}:deny Refuse it.

A code is single use and lasts 15 minutes. Looking codes up, approving and denying are rate-limited together, so a code cannot be guessed. The approval does not carry the token: only the box that holds the other code can collect it.

3. Collect the token #

POST /v1/oauth/token

The box polls this every interval seconds until its owner decides (RFC 8628 section 3.4).

On approval the answer carries the access_token. It is a machine token: write-only, bound to the one machine the owner chose, stored only as a hash, listed with that machine's tokens (with issued_by: login) and revocable there. It does not expire and there is no refresh token: to rotate, log in again.

The token is handed over once. A device_code that has been exchanged, or was never issued, gets invalid_grant.

Every other answer is 400 with an OAuth error:

error Meaning What the box does
authorization_pending The owner has not decided yet Keep polling
slow_down Polling faster than interval Add 5 seconds to the interval, keep polling
access_denied The owner said no Stop
expired_token 15 minutes passed Stop; start again
invalid_grant Unknown or already used device_code Stop
unsupported_grant_type, invalid_client, invalid_request The request itself is wrong Stop

Request body #

FieldTypeRequiredMeaning
grant_typealways "urn:ietf:params:oauth:grant-type:device_code"Required
device_codestringRequired
client_idalways "nucleate"Required

The body is form-encoded (application/x-www-form-urlencoded), not JSON.

Responses #

StatusMeaning
200The machine token, and what it is for.
400An OAuth error; see the table above.

When the owner has approved, the answer is:

FieldTypeRequiredMeaning
access_tokenstringRequiredA machine token. Handed over once; Watch keeps only a hash.
token_typealways "Bearer"Required
scopealways "ingest"Required
machine_idstringRequired
machine_namestringRequired
account_namestringRequired

Any field that is not in this table is rejected, and the request with it.

access_token is the machine token. nucleate login writes it to ~/.config/nucleated/token, readable by the agent user only, and prints the machine and account names so a box signed in to the wrong account is obvious at once.

Until then, and when anything is wrong, the answer is an error:

An OAuth 2.0 error response (RFC 6749 section 5.2), used by /v1/oauth/* only.

FieldTypeRequiredMeaning
errorstring, one of the values listedRequiredOne of: authorization_pending, slow_down, access_denied, expired_token, invalid_grant, invalid_request, invalid_client, invalid_scope, unsupported_grant_type.
error_descriptionstringOptional

Any field that is not in this table is rejected, and the request with it.

Give the token up #

POST /v1/oauth/revoke

nucleate logout (RFC 7009). Holding the token is what authorizes revoking it. The answer is 200 whether or not the token was known, so the endpoint says nothing about which tokens exist.

Request body #

FieldTypeRequiredMeaning
tokenstringRequiredThe machine token to revoke.
token_type_hintstringOptionalAccepted and ignored.
client_idstringOptional

The body is form-encoded (application/x-www-form-urlencoded), not JSON.

Responses #

StatusMeaning
200The token, if it was one, no longer works.
400invalid_request: no token was sent.
429Too many requests from one address (slow_down).

nucleate logout sends this, then deletes the token from the box whatever the answer. Holding the token is what authorises revoking it, and the answer is the same whether or not the token was known.

Without the flow #

A token can also be minted in the console, on a machine's page, and stored on a box with nucleate login --token-stdin. That makes no request at all. Both kinds of token are the same thing afterwards: write-only, bound to one machine, and listed and revocable in the console.