Node.js cli auth with device code flow: what it changes

At a glance

What this is: This is a tutorial for adding OAuth 2.0 Device Code authentication to a Node.js CLI, with the key finding that browser-mediated login can replace manual token handling in terminal tools.

Why it matters: It matters because CLI authentication is part of the identity perimeter now, and IAM teams need to understand how device-bound login, token polling, and user verification affect NHI governance and account assurance.

👉 Read WorkOS's Node.js CLI tutorial for device code authentication

Context

Node.js CLI authentication is the problem space here, not just a coding pattern. When a terminal tool needs user login but cannot embed a browser, the usual human IAM assumptions change because the device becomes the session initiator while the browser remains the authenticating surface.

That matters for identity governance because the flow blends human authentication with a non-human execution context. The CLI is still a workload, but the user approval happens elsewhere, so teams need to think about how device codes, access tokens, and polling intervals fit into broader access control and session management policies.

Key questions

Q: How should teams govern browser-based login for a command-line tool?

A: Treat it as delegated identity, not a lightweight auth shortcut. The browser step authenticates the person, but the CLI becomes the operational identity that receives and uses tokens. Governance should cover approval traceability, token scope, storage, revocation, and whether the resulting session is auditable across human and workload boundaries.

Q: When does device code authentication become risky for enterprise use?

A: Risk rises when the issued tokens are long-lived, over-scoped, or stored in places the organisation cannot control. The flow is usually acceptable for constrained clients, but it becomes problematic if the CLI can reuse bearer tokens beyond the intended task or if revocation and expiry are not enforced.

Q: What do security teams get wrong about CLI login flows?

A: They often focus on the browser approval step and ignore the non-human token lifecycle that follows. The real governance issue is whether the CLI can handle bearer credentials safely, whether logs and caches leak them, and whether access can be revoked quickly when the session is no longer needed.

Q: How do you know if a device code flow is operating within its intended boundary?

A: You should see bounded polling, narrow scopes, clear timeout behaviour, and no token leakage into logs or persistent storage. If the CLI is continuously polling, retaining old tokens, or requesting broad API access for a simple task, the flow has moved outside its intended security boundary.

Technical breakdown

OAuth 2.0 device code flow in CLI authentication

The Device Authorization Grant is designed for input-constrained clients such as CLIs, TVs, and other apps that cannot safely host a browser. The client first requests a device code and a user code, then asks the user to complete login in a separate browser session. The terminal app never handles the primary credentials directly; it exchanges the device code for tokens after the user authorises the session. This separates user interaction from application execution, but it also creates a narrow trust bridge between the device and the browser session.

Practical implication: treat the device code exchange as a governed authentication flow, not a convenience shortcut.

Polling, slow_down handling, and token issuance timing

Polling is the core runtime mechanism in this flow. The CLI repeatedly checks the token endpoint at the interval returned by the authorization server, then waits on authorization_pending, backs off on slow_down, and stops on terminal errors such as access_denied or expired_token. This is not just implementation detail. It is an authentication control loop with built-in timing constraints, and the client must respect them to avoid noisy retries or unnecessary load. The timeout also prevents the CLI from waiting forever when user approval never arrives.

Practical implication: build explicit timeout and backoff logic so token polling remains bounded and predictable.

Access tokens, refresh tokens, and terminal trust boundaries

Once authorization succeeds, the CLI receives tokens that can be used for API calls and potentially renewed later. That means the security boundary shifts from login to token stewardship, because the CLI now holds bearer credentials in a local runtime environment. In NHI terms, the tool is operating with delegated identity, even if the initial approval came from a human. The main risk is not the browser step itself but the lifecycle of the issued tokens, their scope, and where they are stored or logged.

Practical implication: minimise token exposure in the CLI runtime and define clear storage and revocation rules for issued credentials.

Breaches seen in the wild

• Salesloft OAuth token breach — hackers stole OAuth tokens to access Salesforce data via Salesloft.
• Internet Archive breach — unsecured GitLab authentication tokens exposed 31M Internet Archive accounts.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Device code login is still an identity governance problem, not just a UX pattern. The CLI is a non-human execution context, but the approval step is human-mediated through a browser. That means the security model depends on how well the organisation governs delegated access between a person and a workload. For practitioners, the real question is whether the login flow is auditable, scoped, and revocable when the terminal becomes a trust boundary.

The trust window is defined by token stewardship, not by the browser step. Once the device code is exchanged, the CLI is holding bearer credentials that can be used outside the original login moment. That is classic NHI territory, even when the identity behind the session is human. The implication is that lifecycle, storage, and revocation controls matter more than the fact that the user approved the flow in a browser.

Delegated CLI authentication creates a mixed identity pattern that teams often under-model. Human authentication, workload execution, and access token use are all part of one chain, but they are governed differently. Security teams that only review the human login will miss the non-human access path, while teams that only focus on the CLI will miss the accountability layer. Practitioners should model the full delegation chain as one identity event.

Short-lived device codes reduce one kind of exposure, but they do not eliminate entitlement risk. The flow still issues tokens that can reach APIs, which means permission scope, token lifetime, and revocation response determine the actual blast radius. The named concept here is delegated terminal trust: a browser-approved workload session that inherits human authority but behaves as an operational identity. Teams need to govern the inherited authority, not just the login screen.

From our research:

• 1 in 4 organisations are already investing in dedicated NHI security capabilities, with an additional 60% planning to do so within the next twelve months, according to The State of Non-Human Identity Security.
• Only 1.5 out of 10 organisations are highly confident in their ability to secure NHIs, compared with nearly 1 in 4 for securing human identities, according to the same survey.
• For a broader view of how identity governance breaks down in machine contexts, see Ultimate Guide to NHIs - 2025 Outlook and Predictions.

What this signals

Delegated terminal trust: device code login creates a human-approved workload session, which means governance has to follow the token, not just the browser. If the CLI can hold bearer credentials, the programme has entered NHI territory even when the original authenticator was a person.

The control signal to watch is whether teams can inventory where terminal-issued tokens live, how long they remain valid, and who can revoke them. That is where the identity boundary becomes operational, and where access review processes often fail to see the full path.

For practitioners building out the next phase of CLI governance, the structural issue is confidence. Only 1.5 out of 10 organisations are highly confident in their ability to secure NHIs, according to The State of Non-Human Identity Security, so terminal-authenticated workloads should be treated as a governance backlog, not a niche developer feature.

For practitioners

• Classify CLI login as delegated identity Map terminal-based login flows to both the human authenticator and the workload that will use the issued tokens. Record the approval path, token audience, and runtime owner so the access event is reviewable as an identity transaction rather than a one-off script action.
• Bound polling and token lifetime Respect the server-provided interval, enforce a hard timeout, and avoid indefinite polling loops. Pair the runtime with token expiry and revocation handling so stale device codes and old bearer tokens do not persist beyond the intended session.
• Restrict token handling in the CLI process Never print access tokens, avoid writing them to shell history or debug logs, and prefer in-memory use only unless a governed storage pattern exists. If refresh tokens are issued, define where they may live and who can revoke them.
• Review scope before shipping the CLI Limit the scopes requested by the device flow to the minimum API set the tool actually needs. Then validate that the resulting token cannot be reused for broader downstream actions than the CLI should perform.

Key takeaways

• CLI device code login turns a terminal app into a delegated identity flow that must be governed like other non-human access paths.
• The main security boundary is token stewardship after approval, not the browser step itself.
• Teams should control scope, timeout, storage, and revocation together if they want CLI authentication to stay within its intended use.

Key terms

• Device Authorization Grant: A browser-mediated OAuth flow for input-constrained clients such as command-line tools. The client receives a device code and user code, while the user completes authentication elsewhere. It is useful when the application cannot safely host a browser, but the issued tokens still need normal lifecycle control.
• Delegated Identity: An identity pattern where one actor authenticates on behalf of another actor that will actually use the credential. In CLI authentication, the human approves access while the terminal process consumes the token. Governance must account for both the approving subject and the operating workload.
• Bearer Token Stewardship: The discipline of controlling where bearer credentials are stored, logged, refreshed, and revoked after issuance. For command-line tools, this is the main security boundary because possession is enough to use the token. Without strong handling rules, even short-lived access can create an avoidable exposure window.
• Terminal Trust Boundary: The point at which a command-line application becomes part of the security perimeter because it can hold and use credentials. It is not just a user interface issue. The terminal process, its logs, caches, and surrounding scripts all affect whether the resulting access remains governable.

Deepen your knowledge

CLI authentication and delegated token handling are covered in the NHI Foundation Level course, the industry's only accredited NHI security programme. If you are governing terminal-based access in the same way, the course is a practical next step.

This post draws on content published by WorkOS: How to add auth to your Node.js CLI using WorkOS. Read the original.