Skip to main content
The auth command group provides functionality to manage authentication credentials for A2A agents. Credentials are securely stored and automatically used when interacting with agents.

​
set

Set authentication credentials for an agent. You can configure either bearer token or API key authentication. 
handler auth set <agent_url> [OPTIONS]

​
Arguments

​
agent_url
string
required
URL of the A2A agent to set credentials for

​
Options

​
--bearer
string
Bearer token for authentication. Short form: -b
Provide either --bearer or --api-key, not both.
​
--api-key
string
API key for authentication. Short form: -k
Provide either --bearer or --api-key, not both.
​
--api-key-header
string
default:"X-API-Key"
Header name for API key. Only used with --api-key. Default: X-API-Key

​
Examples

handler auth set http://localhost:8000 --bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Output

Set Bearer token for http://localhost:8000

​
Validation

The command validates that:
  • Exactly one of --bearer or --api-key is provided
  • If neither is provided, an error is shown
  • If both are provided, an error is shown
Credentials are stored in ~/.handler/sessions.json. Ensure this file has appropriate permissions to protect sensitive tokens.

​
show

Display authentication credentials for an agent. Credentials are masked for security. 
handler auth show <agent_url>

​
Arguments

​
agent_url
string
required
URL of the A2A agent whose credentials to display

​
Examples

handler auth show http://localhost:8000

​
Output Format

Displays credential information:
  • Type: Authentication type (bearer or api_key)
  • Value: Masked credential value (first 4 and last 4 characters shown)
  • Header: Header name (for API key authentication only)
Auth for http://localhost:8000
Type: bearer
Value: eyJh...CJ9
Credentials are masked to prevent accidental exposure. Only the first and last 4 characters are shown. Very short credentials (8 characters or less) are shown as ****.

​
clear

Remove authentication credentials for an agent. 
handler auth clear <agent_url>

​
Arguments

​
agent_url
string
required
URL of the A2A agent whose credentials to clear

​
Examples

handler auth clear http://localhost:8000

​
Output

Cleared credentials for http://localhost:8000
After clearing credentials, requests to the agent will be unauthenticated unless you provide credentials inline using --bearer or --api-key flags.

​
Authentication Flow

​
Credential Priority

When making requests to an agent, credentials are resolved in this order:
  1. Inline credentials: --bearer or --api-key flags passed to commands
  2. Saved credentials: Credentials stored via auth set
  3. No authentication: Request is sent without credentials
# Set saved credentials
handler auth set http://localhost:8000 --bearer token-abc

# Uses saved credentials
handler message send http://localhost:8000 "Hello"

# Inline credentials override saved
handler message send http://localhost:8000 "Hello" --bearer token-xyz

​
Authentication Types

​
Bearer Token

Bearer tokens are sent in the Authorization header: 
Authorization: Bearer <token>
Use for:
  • JWT tokens
  • OAuth access tokens
  • Custom bearer authentication schemes

​
API Key

API keys are sent in a custom header (default: X-API-Key): 
X-API-Key: <key>
You can customize the header name: 
handler auth set http://localhost:8000 \
  --api-key my-key \
  --api-key-header X-Custom-Auth
Results in: 
X-Custom-Auth: <key>
Use API key authentication with custom headers when working with agents that expect non-standard authentication headers.

​
Credential Storage

Credentials are stored in ~/.handler/sessions.json alongside session data. The file structure: 
{
  "sessions": {
    "http://localhost:8000": {
      "agent_url": "http://localhost:8000",
      "context_id": "ctx_abc123",
      "task_id": "task_xyz789",
      "credentials": {
        "auth_type": "bearer",
        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "header_name": null
      }
    }
  }
}
Credentials are stored in plain text. Ensure ~/.handler/sessions.json has appropriate file permissions (e.g., chmod 600) to prevent unauthorized access.

​
Working with Authenticated Agents

​
Setting Up Authentication

# Start an authenticated agent
handler server agent --auth --api-key my-secret-key

# Set credentials
handler auth set http://localhost:8000 --api-key my-secret-key

# Verify credentials are saved
handler auth show http://localhost:8000

# Send authenticated request
handler message send http://localhost:8000 "Hello"

# Clear when done
handler auth clear http://localhost:8000

​
Testing Authentication

# Try without credentials (should fail if auth required)
handler message send http://localhost:8000 "Hello"

# Set credentials
handler auth set http://localhost:8000 --bearer my-token

# Try again (should succeed)
handler message send http://localhost:8000 "Hello"

​
Integration with Other Commands

All commands that interact with agents support inline authentication: 
# Message commands
handler message send http://localhost:8000 "Hi" --bearer token
handler message stream http://localhost:8000 "Hi" --api-key key

# Task commands
handler task get http://localhost:8000 task_123 --bearer token
handler task cancel http://localhost:8000 task_123 --api-key key

# Card commands (authentication typically not required)
handler card get http://localhost:8000
Inline credentials override saved credentials for that specific command.
Credentials are shared across CLI, TUI, and MCP interfaces. Setting credentials via auth set makes them available in all Handler interfaces.