Product Guides are now only available at docs.box.com. Check out all the details on what's changed.

Box Status
Print

Box CLI: "Login failed: Failed to exchange auth code for tokens."

Summary

When you run box login with OAuth, your browser may complete sign-in and Grant access, and open a page such as http://localhost:3000/callback?code=...&state=..., but the command line still shows:

Login failed: Failed to exchange auth code for tokens.

This usually means Box accepted the authorization in the browser, but Box CLI could not finish exchanging that authorization for access tokens. On networks that require a corporate proxy, the browser may already use the proxy while Box CLI does not, unless you configure proxy settings for the CLI.

Symptoms

You may see all of the following:

  • After box login, the CLI opens a browser and shows a message to click Grant access to Box
  • You sign in successfully and see the Grant access page
  • After you click Grant access, the browser address bar shows http://localhost:3000/callback (or another port you chose) with code and state in the URL
  • The browser page says Login failed. Please check the CLI output for details.
  • The CLI ends with Login failed: Failed to exchange auth code for tokens.

Cause

OAuth login has two steps after you click Grant access:

  1. Your browser redirects to a local address on your computer, such as http://localhost:3000/callback, so Box CLI can receive the authorization code.
  2. Box CLI then contacts Box over the internet to exchange that code for access tokens.

This article covers failures at step 2. The browser may reach localhost successfully, but login still fails if Box CLI cannot reach Box—for example when a corporate proxy is required and is not configured for the CLI.

Resolution

1. Confirm your app settings (custom Platform App only)

Skip this step if you authenticate with the official Box CLI app (for example you choose Log-in as a Box user (OAuth) or use box login --default-box-app / box login -d). That flow does not use your own Client ID in Developer Console.

If you use your own Platform App (you enter a Client ID and Client Secret at box login), open that app in the Box Developer Console and check:

  • Redirect URI matches the callback URL used by the CLI. The default is http://localhost:3000/callback. If you use box login --port, the Redirect URI must use that same port.
  • The Client ID and Client Secret you enter at box login are correct.

Save any changes, then try box login again.

2. Check whether Box CLI is using your proxy

View the current CLI settings:

box configure:settings

Look for Enable proxy and the proxy URL. If proxy is disabled or the URL is empty, and your network requires a proxy to reach the internet, configure it.

Set the proxy URL (include the protocol, host, and port). Enabling the proxy alone is not enough—you must also set the URL:

box configure:settings --enable-proxy --proxy-url=http://PROXY_HOST:PORT

Replace PROXY_HOST and PORT with values from your IT or network team. If your proxy requires a username and password, add:

--proxy-username=YOUR_USERNAME --proxy-password=YOUR_PASSWORD

Then run box login again on the same computer.

For more information, please refer to https://github.com/box/boxcli/blob/main/docs/configuration.md#setting-up-proxy 

3. Optional: set proxy environment variables for one session

You can set proxy variables for the current terminal session, then run login. Use the http:// prefix, and set both http_proxy and https_proxy. Token exchange uses HTTPS, so setting only http_proxy may not be enough.

Windows Command Prompt

set http_proxy=http://PROXY_HOST:PORT
set https_proxy=http://PROXY_HOST:PORT
box login

macOS / Linux (bash or zsh)

export http_proxy=http://PROXY_HOST:PORT
export https_proxy=http://PROXY_HOST:PORT
box login

4. If login still fails

Try the following with help from your IT or network team if needed:

  1. Run the same box login on a network path that does not require the proxy, or where Box traffic is already allowed.
  2. Ask whether SSL inspection or a security product affects command-line tools differently from the browser.
  3. Optionally try box login --code if your environment makes the local browser callback difficult. Token exchange still runs from the CLI to Box, so proxy settings may still be required.

Ask your network team to confirm that Box CLI can reach Box over HTTPS (including api.box.com) through your proxy or firewall.

If the issue continues after those checks, contact Box Support. Include:

  • The Box user email used for login
  • Box CLI version (box --version)
  • Operating system
  • Whether you use a corporate proxy or SSL inspection
  • OAuth app Client ID (do not send the Client Secret) if using your own app
  • The exact CLI error message
  • Date and time of a recent failed attempt, including timezone
  • Confirmation that the browser opened http://localhost:<port>/callback?code=...&state=... after Grant access
  • Output of box configure:settings (remove any proxy password before sharing)
  • Browser network logs from the failing Grant access attempt (with Preserve log enabled) and the full CLI output
  • What you already tried (CLI proxy settings, environment variables, another network, box login --code)

How to confirm it is fixed

  • After Grant access, the browser opens the localhost callback URL and the CLI reports a successful login
  • A command that requires authentication, such as box users:get me, works
  • If your network requires a proxy, box configure:settings shows the correct proxy as enabled

Related articles