axauth

Unified authentication management for AI coding agents.

Overview

axauth provides a consistent interface for managing credentials across multiple AI coding agent CLIs. It abstracts away the differences between agent-specific credential storage mechanisms (macOS Keychain, file-based storage, environment variables) and provides:

• Auth status detection - Check which agents are authenticated and via which method
• Credential extraction - Extract tokens for API calls or export/import workflows
• Portable credential export - Encrypted credential files for CI/CD and backup
• Multi-storage support - Keychain (macOS), file storage, and environment variables

Supported Agents

| Agent | CLI | Provider | Auth Methods | | ----------- | ---------- | --------- | ------------------------------------------ | | Claude Code | claude | Anthropic | OAuth (keychain/file), ANTHROPIC_API_KEY | | Codex CLI | codex | OpenAI | ChatGPT OAuth, OPENAI_API_KEY | | Gemini CLI | gemini | Google | OAuth, GEMINI_API_KEY | | OpenCode | opencode | Sst | Multi-provider OAuth | | Copilot CLI | copilot | GitHub | OAuth, GH_TOKEN/GITHUB_TOKEN |

Installation

npm install axauth
# or
pnpm add axauth

CLI Usage

# List agents and their auth status
axauth list
axauth list --json

# Get access token for an agent (outputs raw token for piping)
axauth token --agent claude
axauth token --agent opencode --provider anthropic  # OpenCode requires --provider

# Export credentials to encrypted file
axauth export --agent claude --output creds.json
axauth export --agent claude --output creds.json --no-password

# Install credentials from exported file
axauth install-credentials --agent claude --input creds.json
axauth install-credentials --agent claude --input creds.json --config-dir /tmp/config

# Remove credentials (agent will prompt for login on next use)
axauth remove-credentials --agent claude
axauth remove-credentials --agent claude --config-dir /tmp/config

Pipeline Examples

The CLI outputs TSV format for easy processing with standard Unix tools:

# List all agents and their auth status
axauth list
# AGENT    STATUS          METHOD
# claude   authenticated   OAuth (max)
# codex    authenticated   ChatGPT OAuth
# ...

# Filter to show only authenticated agents
axauth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'

# Count agents by status
axauth list | tail -n +2 | cut -f2 | sort | uniq -c

# Check if a specific agent is authenticated
axauth list --json | jq -e '.[] | select(.agentId == "claude") | .authenticated'

# Use token with curl
curl -s -H "Authorization: Bearer $(axauth token --agent claude)" \
  -H "anthropic-beta: oauth-2025-04-20" \
  https://api.anthropic.com/api/oauth/usage | jq .

Library API

import {
  // Core operations
  checkAuth, // Check single agent auth status
  checkAllAuth, // Check all agents' auth status
  getAgentAccessToken, // Get access token for an agent
  findCredentials, // Find credentials from storage or environment
  installCredentials, // Install credentials to storage
  removeCredentials, // Remove credentials from storage

  // Credential utilities
  getAccessToken, // Extract token from credential object
  credentialsToEnvironment, // Convert credentials to env vars
  getCredentialsEnvironmentVariableName, // Get AX_*_CREDENTIALS var name
  installCredentialsFromEnvironmentVariable, // Install from env var (CI/CD)

  // Adapter access
  getAdapter, // Get adapter for an agent
  getAllAdapters, // Get all adapters
  getCapabilities, // Check adapter capabilities
} from "axauth";

// Types
import type {
  AgentCli, // "claude" | "codex" | "gemini" | "opencode" | "copilot"
  AuthStatus, // { agentId, authenticated, method?, details? }
  Credentials, // { agent, type, data }
  AuthAdapter, // Adapter interface
  AdapterCapabilities, // { keychain, file, environment, installApiKey }
} from "axauth";

Examples

import { checkAuth, getAgentAccessToken, getCapabilities } from "axauth";

// Check auth status for an agent
const status = checkAuth("claude");
if (status.authenticated) {
  console.log(`Authenticated via ${status.method}`);
}

// Get access token for API calls
const token = await getAgentAccessToken("claude");
if (token) {
  // Use token for API calls
}

// OpenCode requires explicit provider (multi-provider agent)
const openCodeToken = await getAgentAccessToken("opencode", {
  provider: "anthropic",
});

// Check adapter capabilities
const caps = getCapabilities("gemini");
if (!caps.keychain) {
  console.log("Gemini requires file storage on this platform");
}

Adapter Pattern

Each agent implements the AuthAdapter interface, hiding storage complexity:

import { getAdapter } from "axauth";

const adapter = getAdapter("claude");

// All adapters have the same interface (OpenCode requires { provider } option)
const status = adapter.checkAuth();
const creds = adapter.findStoredCredentials(); // OpenCode: findStoredCredentials({ provider: "anthropic" })
const token = adapter.getAccessToken(creds);
const envVars = adapter.credentialsToEnvironment(creds);

// Check what the adapter supports
console.log(adapter.capabilities);
// { keychain: true, file: true, environment: true, installApiKey: false }

Adapter Capabilities

Each agent adapter declares its storage capabilities:

| Agent | Keychain | File | Environment | Install API Key | | -------- | :------: | :--: | :---------: | :-------------: | | claude | macOS | Yes | Yes | No (env-only) | | codex | macOS | Yes | Yes | No (env-only) | | gemini | macOS | Yes | Yes | No (env-only) | | opencode | No | Yes | Yes | No | | copilot | macOS | Yes | Yes | No (env-only) |

Notes:

• Keychain: macOS Keychain support (not available on Linux/Windows)
• File: File-based credential storage
• Environment: Can read credentials from environment variables
• Install API Key: Whether API keys can be installed (vs. read from env only)

Credential Export Format

Exported credentials are encrypted with AES-256-GCM:

{
  "version": 1,
  "agent": "claude",
  "ciphertext": "<base64>",
  "salt": "<base64>",
  "iv": "<base64>",
  "tag": "<base64>"
}

• Key derivation: PBKDF2 with SHA-256, 100,000 iterations
• Use --no-password for CI/CD (uses a default password)
• Files are written with 0o600 permissions

Environment Variables

For CI/CD workflows, credentials can be passed via environment variables:

| Agent | Credential Env Var | | -------- | ------------------------- | | claude | AX_CLAUDE_CREDENTIALS | | codex | AX_CODEX_CREDENTIALS | | gemini | AX_GEMINI_CREDENTIALS | | copilot | AX_COPILOT_CREDENTIALS | | opencode | AX_OPENCODE_CREDENTIALS |

Use installCredentialsFromEnvironmentVariable() to install credentials from these variables programmatically.

Config Directory Requirements

Some agents require specific directory name suffixes:

| Agent | Directory Requirement | Example | | -------- | ------------------------ | -------------------- | | claude | Any name | /tmp/my-config | | codex | Any name | /tmp/my-config | | gemini | Must end with .gemini | /tmp/home/.gemini | | copilot | Must end with .copilot | /tmp/home/.copilot | | opencode | Must end with opencode | /tmp/data/opencode |

Architecture

axauth follows the adapter pattern with a functional core:

src/
├── index.ts              # Public API exports
├── cli.ts                # CLI entry point
├── crypto.ts             # AES-256-GCM encryption
├── commands/
│   └── auth.ts           # CLI command handlers
└── auth/
    ├── adapter.ts        # AuthAdapter interface
    ├── types.ts          # AuthStatus, Credentials types
    ├── registry.ts       # Adapter registry and unified operations
    └── agents/           # Agent-specific adapters
        ├── claude-code.ts
        ├── claude-code-storage.ts
        ├── codex.ts
        ├── codex-storage.ts
        ├── codex-config.ts
        ├── gemini.ts
        ├── gemini-storage.ts
        ├── gemini-auth-check.ts
        ├── copilot.ts
        ├── copilot-storage.ts
        ├── copilot-auth-check.ts
        └── opencode.ts

Related Packages

axauth is part of the a╳kit ecosystem:

• axshared - Shared types and agent metadata
• axconfig - Permission and configuration management
• axrun - Agent execution and output normalization

License

MIT