Device Authorization

Reference for the OAuth 2.0 device authorization grant flow used by the Nscale CLI, including endpoints, timing, and security notes.

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