Authenticate CLI tools seamlessly with OAuth Device Flow

Today, we're launching CLI Authentication for AuthKit, bringing OAuth 2.0 Device Authorization Grant Flow to hosted AuthKit customers.

This feature enables your users to securely authenticate command-line applications using the same trusted AuthKit experience they are familiar with from your web app, now available to all hosted AuthKit customers at no additional cost.

In this article, we'll explore how CLI Auth works and how you can implement it to provide your users with a seamless authentication experience for non-traditional devices like TVs and terminal-based tools.

What is CLI Authentication?

Anyone who's built a CLI tool knows the authentication challenge: how do you securely authenticate users without a browser?

Traditional approaches, such as storing API keys in configuration files or environment variables, pose security risks and lead to poor user experiences.

The OAuth 2.0 Device Authorization Grant Flow, which we refer to as CLI Auth, elegantly solves this issue.

You've probably used this flow before when logging into streaming apps on your TV—you see a code on screen, visit a URL on your phone, and magically you're logged in.

From a user's perspective, CLI Auth works like this: they run a command in their terminal (like mycli login), see a short code and URL, visit that URL in their browser to authenticate, and their CLI tool is instantly authorized.

No copying long API keys, no insecure credential storage—just a secure and easy-to-complete flow.From a technical perspective, CLI Auth implements the OAuth 2.0 Device Authorization Grant Flow specification.

When a user initiates authentication, the CLI requests a device code from your AuthKit instance. This code is displayed to the user along with a verification URL. Once the user completes authentication in their browser, the CLI tool receives the authorization tokens it needs to act on the user's behalf.

Implement CLI Auth with WorkOS

To start using CLI Auth, ensure you're using hosted AuthKit (this feature is not available for headless AuthKit implementations). The feature is automatically available—no configuration needed.

Your CLI application initiates the device authorization flow by making a request to the device authorization endpoint. See the docs to get started.

# Your CLI displays:
# Please visit: https://your-app.com/device 
# And enter code: WDJB-MJHT 

Or visit: https://your-app.com/device?user_code=WDJB-MJHT

The user visits the URL, sees your familiar AuthKit login screen, and enters the code (or it's pre-filled if they used the direct URL). After authenticating, they see a confirmation screen, and your CLI receives the access tokens.

Security benefits

CLI Auth provides significant security advantages over traditional CLI authentication methods:

• No long-lived credentials are stored on disk
• Users can revoke access through your standard AuthKit session management
• Authentication happens in the browser, where users can verify your domain
• Supports all AuthKit security features, including MFA and SSO

Get started

CLI Auth is available now for all hosted AuthKit customers. To implement it in your CLI tools, check out our documentation.

‍Get started with AuthKit or read the docs to add CLI Auth to your existing implementation today.