OAuth 2.0 Authentication

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

Overview

OAuth 2.0 is an alternative to API key authentication available to all axe MCP Server users. It uses the Authorization Code Flow with PKCE and stores tokens securely in your OS keychain, so you authenticate once and the CLI handles token refresh automatically.

Authentication is managed by @deque/axe-auth, a standalone CLI that you install separately on your host machine.

Prerequisites

  • Node.js 22 LTS or later
  • Docker installed and running

Step 1: Authenticate

Run the login command:

npx @deque/axe-auth login

The CLI will:

  1. Open your default browser to the login page
  2. Prompt you to sign in with your axe Account credentials
  3. Store the resulting tokens securely in your system keychain
note

Your operating system may prompt you to grant keychain access the first time tokens are stored.

When complete, the terminal confirms:

✓ Authenticated.

You only need to run login once per machine. On subsequent invocations, npx @deque/axe-auth token refreshes your access token silently using the stored refresh token.

Private cloud, non-US regions, or on-premises installations

If your organization uses a private cloud or on-premises axe instance, pass your instance URL with --server (or set AXE_SERVER_URL env var):

npx @deque/axe-auth login --server https://your-axe-instance.example.com

Step 2: Configure Your IDE

Use @deque/axe-auth token in your MCP client configuration to inject a valid access token into the Docker container each time the server starts. Wrap the Docker command with sh -c so the shell can substitute the token — MCP configuration files are JSON and don't expand $(...) directly:

note

Set either AXE_API_KEY or AXE_ACCESS_TOKEN — not both. The server will fail at startup if both variables are set.

Choose your IDE for specific setup instructions:

Each setup page includes an OAuth configuration section alongside the API key instructions.

Managing Sessions

Token lifetime

OAuth access tokens are short-lived. If a session runs longer than the token's lifetime, the server will return authentication errors.

Workaround: Restart the MCP server connection in your IDE. The configuration re-runs @deque/axe-auth token on each server startup, which fetches a fresh token automatically.

Logging out

To revoke your tokens server-side and clear them from the system keychain:

npx @deque/axe-auth logout

If server-side revocation fails (for example, due to a network error), local tokens are still cleared and a warning is printed.

Re-authenticating

If your refresh token has expired or been revoked, @deque/axe-auth token exits with code 1 and directs you to log in again. Run npx @deque/axe-auth login again. Pass --force to skip the re-authentication confirmation prompt:

npx @deque/axe-auth login --force

Command Reference

login

Opens a browser, completes the OAuth 2.0 Authorization Code + PKCE flow, and persists tokens to the OS keychain.

npx @deque/axe-auth login [options]
Flag Description
--server <url> Base URL of your axe instance. Defaults to https://axe.deque.com. Only required for private cloud, non-US regions, or on-premises installations.
--force Skip re-authentication confirmation when already logged in.
--allow-insecure-issuer Permit non-loopback http URLs (default is https only; loopback http is always allowed). Applies to login only; token and logout use the policy persisted at login.
--no-allow-insecure-issuer Force allowInsecureIssuer=false for the new login (and the entry it persists). Mutually exclusive with --allow-insecure-issuer. token and logout ignore this flag.

token

Prints a currently-valid access token to stdout. Refreshes silently if the stored token is expired. Exits with code 1 if not authenticated.

npx @deque/axe-auth token

logout

Revokes the stored refresh token server-side and clears the local keychain entry.

npx @deque/axe-auth logout

--help

Displays help information for @deque/axe-auth and its commands.

npx @deque/axe-auth --help
npx @deque/axe-auth <command> --help

Platform Support

Platform Token Storage
macOS macOS Keychain
Windows Windows Credential Manager
Linux D-Bus Secret Service (GNOME Keyring, KWallet, etc.)
caution

Linux: @deque/axe-auth requires a working D-Bus Secret Service. Headless or minimal-desktop environments may not have one available. If you see an error like:

System keychain load failed: <details>. On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).

ask your system administrator to configure GNOME Keyring or a compatible Secret Service provider.

Troubleshooting

Browser does not open automatically

If login cannot open a browser, it prints the authorization URL to the terminal. Copy the URL and open it manually to complete authentication.

Token expiry during long sessions

See Token lifetime above. Restart the MCP server connection in your IDE to obtain a fresh token.

"Not authenticated" error from token

Your session has expired or tokens were cleared. Run npx @deque/axe-auth login again to re-authenticate.

MCP server authentication errors

  • Confirm only AXE_ACCESS_TOKEN is set (not AXE_API_KEY)
  • Confirm AXE_SERVER_URL matches your axe instance URL — this should be the same URL used with --server during login (or https://axe.deque.com if you used the default)
  • Run npx @deque/axe-auth token directly in your terminal to confirm you have a valid token
  • If it exits with code 1, re-authenticate with npx @deque/axe-auth login

Linux keychain unavailable

See the Platform Support callout above.

Is this page helpful?

Help us improve this page

Still need help?