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.
API referenceOn 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.
- The box asks to sign in. It gets two codes: a short one for a person, and a long one it keeps to itself.
- The owner approves. They open
https://app.nucarium.com/activateon a phone or laptop, sign in to Watch, type the short code, and say which machine this box is. - 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
nucleateand 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
errorword, 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 #
| Status | Meaning |
|---|---|
200 | Authorization 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 #
| Field | Type | Required | Meaning |
|---|---|---|---|
client_id | always "nucleate" | Required | |
scope | always "ingest" | Optional | Optional. ingest is the only scope and the default. |
machine_name | string | Optional | Unique 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.
client_id=nucleate&scope=ingest&machine_name=agentbox
Responses #
| Status | Meaning |
|---|---|
200 | The codes, and where the owner goes to approve. |
400 | invalid_request (a parameter is missing, repeated or not valid), invalid_client (not nucleate) or invalid_scope (not ingest). |
429 | Too many sign-ins started from one address (slow_down). Wait Retry-After seconds. |
The answer:
| Field | Type | Required | Meaning |
|---|---|---|---|
device_code | string | Required | The box's secret for this sign-in. Never shown to anyone. |
user_code | string | Required | Eight letters as XXXX-XXXX, from an alphabet with no vowels and no letters that are easily confused. Must match ^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$. |
verification_uri | string (uri) | Required | |
verification_uri_complete | string (uri) | Required | |
expires_in | integer | Required | Seconds both codes last. |
interval | integer | Required | Seconds 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 #
| Field | Type | Required | Meaning |
|---|---|---|---|
grant_type | always "urn:ietf:params:oauth:grant-type:device_code" | Required | |
device_code | string | Required | |
client_id | always "nucleate" | Required |
The body is form-encoded (application/x-www-form-urlencoded), not JSON.
Responses #
| Status | Meaning |
|---|---|
200 | The machine token, and what it is for. |
400 | An OAuth error; see the table above. |
When the owner has approved, the answer is:
| Field | Type | Required | Meaning |
|---|---|---|---|
access_token | string | Required | A machine token. Handed over once; Watch keeps only a hash. |
token_type | always "Bearer" | Required | |
scope | always "ingest" | Required | |
machine_id | string | Required | |
machine_name | string | Required | |
account_name | string | Required |
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.
| Field | Type | Required | Meaning |
|---|---|---|---|
error | string, one of the values listed | Required | One of: authorization_pending, slow_down, access_denied, expired_token, invalid_grant, invalid_request, invalid_client, invalid_scope, unsupported_grant_type. |
error_description | string | Optional |
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 #
| Field | Type | Required | Meaning |
|---|---|---|---|
token | string | Required | The machine token to revoke. |
token_type_hint | string | Optional | Accepted and ignored. |
client_id | string | Optional |
The body is form-encoded (application/x-www-form-urlencoded), not JSON.
Responses #
| Status | Meaning |
|---|---|
200 | The token, if it was one, no longer works. |
400 | invalid_request: no token was sent. |
429 | Too 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.