VOOZH about

URL: https://dev.to/beratbozkurt0/building-github-oauth-device-flow-in-a-nodejs-cli-6e1

⇱ Building GitHub OAuth device flow in a Node.js CLI - DEV Community

When building a CLI tool that needs GitHub access, you have three options:

  1. Ask users to create a personal access token manually (bad UX)
  2. Redirect to a web page (requires a server)
  3. Use the OAuth device flow

The device flow is what the GitHub CLI itself uses. Users run one command, a URL and code appear, they open it in any browser. No server, no copy-pasting tokens. Here's how to implement it cleanly.

The flow in three steps 

1. POST /login/device/code
 → returns: device_code, user_code, verification_uri, expires_in, interval

2. Show the user:
 "Open https://github.com/login/device/activate and enter: XXXX-YYYY"

3. Poll POST /login/oauth/access_token every {interval} seconds
 → returns: access_token (when user completes) or error codes (keep polling)

The implementation is ~100 lines. Most of the complexity is in handling the polling responses correctly.

Polling response codes

This is the part most tutorials skip. The responses aren't HTTP errors — they come back as 200 OK with an error field:

type PollResponse =
 | { access_token: string; token_type: string }
 | { error: 'authorization_pending' } // user hasn't authorized yet — keep polling
 | { error: 'slow_down'; interval: number } // increase interval by 5s
 | { error: 'expired_token' } // time's up — restart the flow
 | { error: 'access_denied' } // user denied — stop

Treating all of these as errors breaks the UX. authorization_pending just means "not yet" — keep the spinner going.

The polling loop 

async function pollForToken(deviceCode: string, intervalSecs: number): Promise<string> {
 let interval = intervalSecs;

 while (true) {
 await sleep(interval * 1000);

 const response = await fetch('https://github.com/login/oauth/access_token', {
 method: 'POST',
 headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
 body: JSON.stringify({
 client_id: CLIENT_ID,
 device_code: deviceCode,
 grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
 }),
 });

 const data = await response.json();

 if ('access_token' in data) return data.access_token;
 if (data.error === 'slow_down') interval += 5;
 if (data.error === 'expired_token') throw new Error('Authorization timed out. Run auth login again.');
 if (data.error === 'access_denied') throw new Error('Authorization denied.');
 // authorization_pending: continue loop
 }
}

Token storage

Write to ~/.toolname/config.json and immediately chmod:

import { writeFileSync, chmodSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';

const configPath = join(homedir(), '.releasehub', 'config.json');
writeFileSync(configPath, JSON.stringify({ githubToken: token }), 'utf-8');
chmodSync(configPath, 0o600); // owner read/write only

Most CLIs skip the chmod and leave the token world-readable. Don't.

The full implementation is in ReleaseHub — a CLI for generating release notes from GitHub PRs. The auth module is standalone if you want to adapt it.