Device Authorization

Quick start: the CLI

For the common case, install our reference CLI. Pure Node.js, no dependencies, single file:

curl -fsSL https://nanostudiopro.com/cli/nsp -o /usr/local/bin/nsp \
  && chmod +x /usr/local/bin/nsp
nsp loginbash

That kicks off the flow below automatically. The token is saved to ~/.config/nsp/credentials.json with mode 0600. To verify:

nsp whoamibash

Other commands: credits, pricing, token, logout. Run nano --help for the full list.

Or do it by hand: the protocol

The CLI is just a friendly wrapper around four HTTP calls. Implement these in any language to build your own client.

1. Request a code

curl -X POST https://nanostudiopro.com/api/device/code \
  -H 'content-type: application/json' \
  -d '{}'bash

Returns:

{
  "device_code": "9p4xN-uw...",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://nanostudiopro.com/device",
  "verification_uri_complete": "https://nanostudiopro.com/device?code=BCDF-GHJK",
  "expires_in": 900,
  "interval": 5
}json

Rate-limited to 10/min/IP. No authentication required — the secret device_code is the bearer of intent.

2. Open the verification URL in a browser

Direct the user to verification_uri_complete (already has the code in the query string), or print user_code and ask them to paste it at verification_uri. They sign in if needed, then click Authorize. They can optionally name the device and set a daily credit cap before confirming — useful as a leak-mitigation if the token ever escapes the machine.

3. Poll for the token

curl -X POST https://nanostudiopro.com/api/device/token \
  -H 'content-type: application/json' \
  -d '{"device_code":"<paste from step 1>"}'bash

While the user hasn't acted yet:

{ "error": "authorization_pending" }json

After approval (returned exactly once):

{
  "access_token": "sk_sf_live_...",
  "token_type": "bearer"
}json

Poll every interval seconds (5 by default). Faster polling returns slow_down. Other terminal errors: access_denied (user clicked Deny) and expired_token (15 min elapsed without action — restart from step 1).

4. Use the token

curl https://nanostudiopro.com/api/v1/me \
  -H "Authorization: Bearer sk_sf_live_..."bash

The token is a regular Personal Access Token. It works with every endpoint under /api/v1. Manage it (rename, edit daily cap, revoke) from Settings · API Tokens.

Security notes

• Codes expire after 15 minutes. The transient token (between approval and the first successful poll) lives at most that long server-side, then is wiped.
• The user_code alphabet excludes vowels and visually-ambiguous characters (no 0/O/1/I/L), so users don't mistype it under fluorescent lighting.
• Daily caps are enforced in a rolling 24-hour window. Hitting the cap returns HTTP 402 with code: "token_cap_exceeded" even when the wallet still has credits.
• Tokens issued by this flow have full account access; there are no scopes (yet). The daily cap is the primary leak-mitigation.