Device authorization

Device authorization reference

This section provides detailed technical information about the OAuth 2.0 Device Authorization Grant flow used by the CLI.

Overview

The device flow lets a CLI request authorization while the user completes login in a browser on a secondary device. Nscale follows RFC 8628.

Technical details

Session storage

Device sessions are stored in a secure, server-side key-value store. Sessions are never exposed to the client and are automatically expired.

Timing

Parameter	Value	Description
Session TTL	600 seconds (10 min)	Time for user to complete authentication
Token pickup window	60 seconds	Time for CLI to retrieve token after authorization
Polling interval	5 seconds	Minimum interval between polling requests

User codes

User codes are 8 characters in format XXXX-YYYY and use an ambiguity-reduced character set to minimize input errors.

API endpoints

1. Device authorization request

POST /api/oauth2/device Initiates the device authorization flow. Request:

curl -X POST https://console.nscale.com/api/oauth2/device \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<CLI_CLIENT_ID>&scope=openid%20profile%20email"

Response:

{
  "device_code": "550e8400-e29b-41d4-a716-446655440000",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://console.nscale.com/auth/device",
  "verification_uri_complete": "https://console.nscale.com/auth/device?code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

2. Token endpoint (polling)

POST /api/oauth2/token The CLI polls this endpoint until authorization completes. Request:

curl -X POST https://console.nscale.com/api/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=550e8400-e29b-41d4-a716-446655440000" \
  -d "client_id=<CLI_CLIENT_ID>"

Responses:

Status	Error code	Meaning	Action
400	`authorization_pending`	User has not completed auth	Wait `interval` seconds, retry
400	`slow_down`	Polling too fast	Increase interval, retry
400	`access_denied`	User denied request	Stop polling, show error
400	`expired_token`	Session expired	Stop polling, restart flow
200	-	Success	Use returned tokens

Success response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "refresh_token": "eyJ...",
  "expires_in": 3599
}

3. Token refresh

POST /api/oauth2/token Refresh an expired access token. Request:

curl -X POST https://console.nscale.com/api/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<REFRESH_TOKEN>"

Token storage recommendations

Store tokens securely using platform-appropriate mechanisms:

Platform	Recommended storage
macOS	Keychain (`security` command or `keytar` npm package)
Linux	libsecret / GNOME Keyring / encrypted file
Windows	Windows Credential Manager

Example with keytar:

import * as keytar from "keytar";

const SERVICE_NAME = "nscale-cli";
const ACCOUNT_NAME = "default";

async function storeTokens(tokens: TokenResponse): Promise<void> {
  await keytar.setPassword(
    SERVICE_NAME,
    ACCOUNT_NAME,
    JSON.stringify({
      access_token: tokens.access_token,
      refresh_token: tokens.refresh_token,
      expires_at: Date.now() + (tokens.expires_in || 3600) * 1000,
    })
  );
}

Security considerations

Device code phishing

Attackers can socially engineer users into authorizing malicious device codes. Mitigations include:

Short session TTL (10 minutes) limits attack window.
User sees a consent screen with requested scopes.
Users can deny suspicious requests.
Device flow can be disabled if not required.

Brute force code guessing

Mitigations include high-entropy user codes, short TTLs, and consistent error responses to prevent enumeration.

Token leakage

Mitigations include single-use tokens, short pickup windows (60 seconds), and secure server-side session storage.

Polling rate abuse

Mitigations include server-side rate limiting and the slow_down error when polling too fast.

RFC 8628 compliance

Our implementation follows RFC 8628 (OAuth 2.0 Device Authorization Grant):

Requirement	Status	Implementation
Device authorization endpoint	Yes	`POST /api/oauth2/device`
Token endpoint with device_code grant	Yes	`POST /api/oauth2/token`
User code display	Yes	8-character code format `XXXX-YYYY`
Verification URI	Yes	`/auth/device`
Verification URI complete	Yes	`/auth/device?code={user_code}`
expires_in parameter	Yes	600 seconds
interval parameter	Yes	5 seconds
authorization_pending error	Yes	Returned while user authenticating
slow_down error	Yes	Returned when polling too fast
access_denied error	Yes	Returned when user denies
expired_token error	Yes	Returned when session expires

References

RFC 8628 - OAuth 2.0 Device Authorization Grant