OAuth device flow in Go CLIs shifts auth out of the terminal

At a glance

What this is: This is a Go CLI authentication tutorial that uses the OAuth 2.0 Device Authorization Grant to move login into the browser while the terminal polls for tokens.

Why it matters: It matters because CLI authentication often sits at the boundary between human identity and non-human execution, where token handling, polling behaviour, and lifecycle governance can create avoidable access risk.

👉 Read WorkOS's tutorial on adding OAuth device flow to a Go CLI

Context

CLI authentication is not just a developer convenience problem. When a terminal-based tool needs user login, the real question is how to authenticate a human without turning the CLI into a credential collector or a standing-token sink. The primary identity here is human, but the execution surface is a non-human application that must be governed like any other privileged client.

The device flow changes the trust boundary: the CLI asks for a device code, the user completes browser-based verification, and the CLI polls until authorization succeeds or fails. That means access control, token handling, and timeout discipline all become part of the application design rather than an afterthought. For identity teams, this is a useful pattern only if it is paired with strong client registration, safe token storage, and clear revocation paths.

Key questions

Q: How should security teams handle authentication for CLI tools without embedding browser login in the terminal?

A: Use the OAuth 2.0 Device Authorization Grant so the human signs in through a browser while the CLI only requests and exchanges a device code. Register the CLI as a public client, keep scopes minimal, and make sure the terminal never handles a reusable password or client secret. That gives you browser-grade authentication without turning the CLI into a credential store.

Q: Why do CLI authentication flows need the same governance as other non-human identities?

A: Because the CLI is the entity that receives, stores, and reuses tokens after the human authenticates. If those tokens persist, leak, or are over-scoped, the terminal behaves like any other non-human identity with access rights. Governance should cover client registration, token custody, rotation, and revocation, not just the login screen.

Q: What breaks when a CLI prints or logs access tokens after browser sign-in?

A: The authentication ceremony may succeed, but the resulting credential can be copied into logs, shell history, crash dumps, or telemetry. That turns a short-lived login into a reusable secret exposure path. The control failure is not authentication itself, but the absence of strict secret handling after token issuance.

Q: How can organisations decide whether device flow is appropriate for a CLI application?

A: Use it when the tool cannot safely embed a browser and the user experience would otherwise require pasted credentials. It is appropriate only if the app is registered correctly, token lifetime is bounded, and revocation is defined. If the CLI needs long-lived, high-privilege access, treat it as a governed client and reconsider the architecture.

Technical breakdown

OAuth 2.0 device authorization grant in CLI apps

The device authorization grant is designed for input-constrained clients such as terminals, TVs, and other headless interfaces. The CLI requests a device code and user code, then hands the user to a browser for authentication and consent. The identity provider returns tokens only after the browser session authorizes the device code. This avoids embedding a browser in the CLI and keeps the primary authentication ceremony in a web context where stronger controls, session policies, and MFA can be applied.

Practical implication: treat the CLI as a public client and keep the browser as the place where the human proves identity.

Polling, timeout, and token handling in terminal auth flows

Device flow is not a one-shot call. The CLI must poll the token endpoint at the interval returned by the authorization server, back off when told to slow down, and stop when authorization is denied or the code expires. That polling loop becomes a control surface of its own because it governs how long a device code remains useful and how much load the client creates. Once tokens are returned, they must be handled as secrets, not log output or debug data.

Practical implication: enforce bounded polling, suppress token display, and store the resulting credentials with the same care as any other secret.

Public client registration and browser handoff for secure CLI auth

A CLI app using device flow should be registered as a public client, because it cannot safely protect a confidential client secret. The browser handoff lets the identity provider apply the normal web authentication stack, while the CLI only receives the resulting authorization artifacts. That architecture is better than asking users to paste tokens into a shell, but it still depends on sound client scoping, correct redirectless flow handling, and explicit token expiry behaviour.

Practical implication: register the CLI correctly, scope it narrowly, and remove any assumption that a terminal client can safely hold long-lived secrets.

Breaches seen in the wild

• Salesloft OAuth token breach — hackers stole OAuth tokens to access Salesforce data via Salesloft.
• Shai Hulud npm malware campaign — Shai Hulud campaign: npm malware exposed secrets on GitHub.

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

NHI Mgmt Group analysis

CLI login flows expose a governance blind spot when teams treat a terminal app like a disposable utility instead of an identity-bound client. The device code pattern pushes human authentication into the browser, but the CLI still becomes the recipient of tokens and the operator of the polling loop. That makes the CLI a governed identity surface, not just a user interface. Practitioners should classify the client, the token lifetime, and the storage path before they classify the feature as 'just authentication.'

Token handling in CLI tools is a standing secret problem disguised as an onboarding problem. If access tokens or refresh tokens are printed, logged, cached, or reused beyond the intended session, the terminal becomes an NHI exposure point even when the user authenticates correctly. This is the same structural failure seen in many secret-exposure incidents: the authentication ceremony succeeds, but the resulting credential is not contained. The practitioner conclusion is simple: token custody matters as much as login success.

Device flow works because it separates human proof from machine execution, but that separation only holds when the client behaves like a bounded NHI. The CLI must not accumulate privileges, retain tokens indefinitely, or poll without a defined stop condition. OAuth 2.0 and Zero Trust principles both depend on explicit session boundaries, so the real governance task is to keep the terminal client inside those boundaries. Practitioners should review every CLI that authenticates users as a non-human identity with a lifecycle.

Named concept, terminal-bound credential exposure: this pattern creates a narrow but real risk that a CLI becomes the place where user-authenticated credentials persist outside the browser session. The problem is not the device flow itself. The problem is the boundary between human authentication and non-human token custody, which must be designed as an identity lifecycle, not a convenience feature. Practitioners should treat CLI auth as governed issuance plus governed storage.

Browser-mediated CLI authentication is useful precisely because it avoids one of the oldest anti-patterns in tooling: pasted credentials. But the governance burden simply moves downstream into app registration, token lifetime, and revocation hygiene. That means identity teams, not just developers, need a say in which CLIs may authenticate users and how their tokens are constrained. Practitioners should standardise the pattern instead of letting every tool invent its own login ritual.

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.
• 85% of organisations lack full visibility into third-party vendors connected via OAuth apps, showing that delegated access remains a governance blind spot.
• Browser-mediated login reduces credential handling risk, but it does not remove the need for lifecycle controls across issued tokens and connected applications.

What this signals

CLI authentication is converging with broader NHI governance because the terminal client becomes the custodian of a human-approved access artefact. As more tooling moves toward browser-mediated login, the governance question shifts from 'how do users authenticate?' to 'how are issued tokens scoped, stored, and revoked?'. Teams should expect the same lifecycle discipline they already apply to other non-human clients.

Terminal-bound credential exposure: this is the failure mode to watch when CLI tools are allowed to print, cache, or reuse access tokens outside the browser session. The control objective is not just secure sign-in, but secure post-authentication custody. That is where identity programmes can align developer convenience with access governance without overcorrecting into friction.

The practical next step is to standardise CLI app registration, token retention limits, and revocation workflows so terminal tools do not become unmanaged access paths. This is where the NHI and human identity programmes intersect: one party proves identity, another party holds the resulting credential, and both require governance.

For practitioners

• Register CLI tools as public clients only Treat the terminal app as a public OAuth client and avoid any design that depends on protecting a client secret inside the executable. Narrow the app registration to the minimum scopes required for the workflow.
• Bound the polling loop and honour expiry signals Use the authorization server interval, increase backoff on slow_down responses, and stop polling on access_denied or expired_token. Add a hard timeout so the device code cannot remain useful indefinitely.
• Handle returned tokens as secrets Do not print access tokens or refresh tokens to the terminal, logs, telemetry, or crash reports. Store them only in approved secret storage or session memory that matches the token lifetime.
• Review CLI token lifecycle as part of access governance Define who can approve CLI applications, how tokens are revoked, and what happens when a user leaves or a tool is retired. The browser login is only one step in the full access lifecycle.

Key takeaways

• CLI browser-login patterns reduce password handling, but they create a governed token custody problem in the terminal.
• The main risk is not the device flow itself. It is the absence of bounded polling, safe storage, and clear revocation for the issued tokens.
• Identity teams should treat browser-authenticated CLI tools as public non-human clients with lifecycle controls, not as harmless developer utilities.

Key terms

• OAuth 2.0 Device Authorization Grant: A browser-assisted OAuth flow for devices or clients that cannot safely host an interactive login experience. The client requests a device code, the user authenticates in a separate browser session, and the client later exchanges that code for tokens. In CLI contexts, it creates a clean split between human proof and machine token custody.
• Public OAuth Client: An application that cannot safely keep a client secret and therefore must be treated as externally visible in its trust model. For CLI tools, this usually means the app can initiate authorization but should not rely on hidden credentials for authentication. The security boundary shifts to scope control, token handling, and revocation.
• Token Custody: The operational responsibility for where an issued token is stored, logged, reused, and eventually revoked. In non-human identity programmes, custody is as important as issuance because a valid token is a reusable access artefact. Poor custody turns successful authentication into a standing exposure problem.
• Terminal-Bound Credential Exposure: A failure mode where a CLI or shell environment becomes the place that sensitive tokens, keys, or session artefacts persist beyond the intended browser session. It usually appears when tools print secrets, cache them unsafely, or keep them alive longer than the access need. The control question is custody, not login success.

Deepen your knowledge

CLI authentication patterns and token lifecycle governance are covered in our NHI Foundation Level course, the industry's only accredited NHI security programme. If your team is standardising browser-mediated login for developer tools, this is a practical place to build the governance baseline.

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