API Keys - AXON

AXON requires API keys to interact with LLM providers and external tool services. This guide covers how to obtain, configure, and manage these credentials.

Overview

AXON separates credentials into two categories:

Backend API Keys — For LLM providers (Anthropic, OpenAI, Gemini)
Tool API Keys — For external services (WebSearch, etc.)

None are required for development. AXON provides stub implementations that work without any API keys. Use --tool-mode stub for testing.

Environment Configuration

Using .env File (Recommended)

Copy the example configuration:

cp .env.example .env

Edit .env with your API keys:

# .env
ANTHROPIC_API_KEY="sk-ant-api03-..."
OPENAI_API_KEY="sk-proj-..."
API_KEY_GEMINI="AIza..."
SERPER_API_KEY="..."

AXON automatically loads .env files in the working directory.

Never commit .env to version control. The .gitignore includes this file by default.

Using Shell Environment

Alternatively, export variables in your shell:

export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."
export API_KEY_GEMINI="AIza..."
export SERPER_API_KEY="..."

Add these to your shell profile for persistence:

# ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."

Backend API Keys

Anthropic (Claude)

Variable: ANTHROPIC_API_KEY Get your key: console.anthropic.com Format: sk-ant-api03-... Models Used:

claude-3-5-sonnet-20241022 (default)
claude-3-opus-20240229
claude-3-haiku-20240307

Setup:

export ANTHROPIC_API_KEY="sk-ant-api03-..."
axon run program.axon --backend anthropic

Pricing (as of March 2026):

Claude 3.5 Sonnet: $3/MTok input,$ 15/MTok output
Claude 3 Opus: $15/MTok input,$ 75/MTok output
Claude 3 Haiku: $0.25/MTok input,$ 1.25/MTok output

Free Tier: $5 credit for new accounts

OpenAI (GPT)

Variable: OPENAI_API_KEY Get your key: platform.openai.com Format: sk-proj-... or sk-... Models Used:

gpt-4-turbo-preview
gpt-4o
gpt-4

Setup:

export OPENAI_API_KEY="sk-proj-..."
axon run program.axon --backend openai

Pricing (as of March 2026):

GPT-4 Turbo: $10/MTok input,$ 30/MTok output
GPT-4o: $5/MTok input,$ 15/MTok output
GPT-4: $30/MTok input,$ 60/MTok output

Free Tier: $5 credit for new accounts (expires after 3 months)

Google Gemini

Variable: API_KEY_GEMINI Get your key: aistudio.google.com Format: AIza... Models Used:

gemini-1.5-pro
gemini-1.5-flash

Setup:

export API_KEY_GEMINI="AIza..."
axon run program.axon --backend gemini

Pricing (as of March 2026):

Gemini 1.5 Pro: $3.50/MTok input,$ 10.50/MTok output
Gemini 1.5 Flash: $0.35/MTok input,$ 1.05/MTok output

Free Tier: 15 requests per minute with generous token limits

Ollama (Local Models)

Variable: None (runs locally) Setup: Install and run Ollama:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama server
ollama serve

# Pull a model
ollama pull llama3.1

# Use with AXON
axon run program.axon --backend ollama

Models Available:

llama3.1 (8B, 70B, 405B)
mistral
codellama
phi-2
Custom models

Pricing: Free (runs on your hardware) Requirements:

8GB+ RAM for 7B models
16GB+ RAM for 13B models
32GB+ RAM for 70B models

Tool API Keys

Serper (WebSearch)

Variable: SERPER_API_KEY Get your key: serper.dev Used For: WebSearch tool (Google Search API) Setup:

export SERPER_API_KEY="..."
axon run program.axon --tool-mode real

Pricing:

Free: 2,500 queries (one-time)
Paid: $50/month for 100,000 queries

Alternative: Use stub mode:

axon run program.axon --tool-mode stub  # No API key needed

Brave Search (Alternative WebSearch)

Variable: BRAVE_API_KEY Get your key: brave.com/search/api Used For: Alternative WebSearch backend Setup:

export BRAVE_API_KEY="..."
# Configure in program or registry

Pricing:

Free: 2,000 queries/month
Paid: Starting at $3/month for 15,000 queries

Tool Modes

AXON supports three tool execution modes:

Stub Mode (Default)

axon run program.axon --tool-mode stub

No API keys required
All tools return mock data
Safe for testing and CI/CD
Deterministic results

Use Cases:

Development without credentials
Unit testing
CI/CD pipelines
Learning AXON

Real Mode

export SERPER_API_KEY="..."
axon run program.axon --tool-mode real

Requires API keys for all used tools
Production-ready execution
Real external API calls
Fails if credentials missing

Use Cases:

Production deployments
Integration testing
Real-world workflows

Hybrid Mode (Recommended)

export SERPER_API_KEY="..."  # Only set what you have
axon run program.axon --tool-mode hybrid

Uses real tools where API keys available
Falls back to stubs automatically
Graceful degradation
Best for mixed environments

Use Cases:

Development with partial credentials
Gradual rollout
Testing with selective real tools

Verification

Test Backend Access

# Create a simple test program
cat > test.axon << 'EOF'
persona TestBot {
  tone: friendly
}

intent Greet() -> str {
  ask: "Say hello"
}

run Greet() as TestBot
EOF

# Test each backend
export ANTHROPIC_API_KEY="..."
axon run test.axon --backend anthropic --tool-mode stub

export OPENAI_API_KEY="..."
axon run test.axon --backend openai --tool-mode stub

export API_KEY_GEMINI="..."
axon run test.axon --backend gemini --tool-mode stub

Test Tool Access

# Create a tool test program
cat > test_tools.axon << 'EOF'
flow SearchTest() -> str {
  step Search {
    use WebSearch("AXON programming language")
    output: str
  }
}

run SearchTest()
EOF

# Test with stub (should work)
axon run test_tools.axon --tool-mode stub

# Test with real backend (requires SERPER_API_KEY)
export SERPER_API_KEY="..."
axon run test_tools.axon --tool-mode real

Security Best Practices

1. Never Commit Secrets

# .gitignore
.env
.env.local
*.key
secrets/

2. Use Environment-Specific Configuration

# Development
cp .env.example .env.dev

# Production
cp .env.example .env.prod

# Load appropriate environment
export $(cat .env.dev | xargs)

3. Rotate Keys Regularly

Set reminders to rotate API keys every 90 days.

4. Use Restricted Keys

Create API keys with minimal required permissions:

Anthropic: Use project-scoped keys
OpenAI: Enable usage limits
Serper: Set request rate limits

5. Monitor Usage

Check API usage dashboards regularly:

Anthropic: console.anthropic.com/settings/usage
OpenAI: platform.openai.com/usage
Gemini: aistudio.google.com/usage

6. Use Secret Management in Production

For production deployments, use secret management services: AWS Secrets Manager:

aws secretsmanager get-secret-value \
  --secret-id axon/api-keys \
  --query SecretString \
  --output text | jq -r '.ANTHROPIC_API_KEY'

HashiCorp Vault:

vault kv get -field=ANTHROPIC_API_KEY secret/axon/api-keys

Kubernetes Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: axon-api-keys
type: Opaque
stringData:
  ANTHROPIC_API_KEY: sk-ant-api03-...
  OPENAI_API_KEY: sk-proj-...

Troubleshooting

”API key not set” Error

✗ Backend error: ANTHROPIC_API_KEY not set

Solution: Verify the environment variable is set:

echo $ANTHROPIC_API_KEY
# Should print your key, not empty

“Invalid API key” Error

Solution:

Check for typos in the key
Verify key format matches provider requirements
Regenerate key from provider dashboard

”Rate limit exceeded” Error

Solution:

Check your usage dashboard
Implement exponential backoff
Upgrade to higher tier if needed

”Insufficient quota” Error

Solution:

Add payment method to provider account
Increase spending limits
Wait for quota reset (free tiers)

Cost Optimization

1. Use Stub Mode for Development

# Free during development
axon run program.axon --tool-mode stub

# Only use real APIs for final testing
axon run program.axon --tool-mode real

2. Choose Appropriate Models

# Use cheaper models for simple tasks
# (Configure in backend implementation)

3. Cache Compiled IR

# Compile once
axon compile program.axon

# Load IR instead of recompiling (when supported)

4. Monitor Token Usage

# Enable tracing to track token consumption
axon run program.axon --trace
cat program.trace.json | jq '
  [.events[] | select(.type=="model_call") | 
   .data.prompt_tokens // 0] | add
'

Tool Modes

Learn about tool execution modes

Backends

Backend-specific configuration

Commands

Configuration

​Overview

​Environment Configuration

​Using .env File (Recommended)

​Using Shell Environment

​Backend API Keys

​Anthropic (Claude)

​OpenAI (GPT)

​Google Gemini

​Ollama (Local Models)

​Tool API Keys

​Serper (WebSearch)

​Brave Search (Alternative WebSearch)

​Tool Modes

​Stub Mode (Default)

​Real Mode

​Hybrid Mode (Recommended)

​Verification

​Test Backend Access

​Test Tool Access

​Security Best Practices

​1. Never Commit Secrets

​2. Use Environment-Specific Configuration

​3. Rotate Keys Regularly

​4. Use Restricted Keys

​5. Monitor Usage

​6. Use Secret Management in Production

​Troubleshooting

​”API key not set” Error

​“Invalid API key” Error

​”Rate limit exceeded” Error

​”Insufficient quota” Error

​Cost Optimization

​1. Use Stub Mode for Development

​2. Choose Appropriate Models

​3. Cache Compiled IR

​4. Monitor Token Usage

​Related Documentation

Tool Modes

Backends

Build docs developers (and LLMs) love

Overview

Environment Configuration

Using .env File (Recommended)

Using Shell Environment

Backend API Keys

Anthropic (Claude)

OpenAI (GPT)

Google Gemini

Ollama (Local Models)

Tool API Keys

Serper (WebSearch)

Brave Search (Alternative WebSearch)

Tool Modes

Stub Mode (Default)

Real Mode

Hybrid Mode (Recommended)

Verification

Test Backend Access

Test Tool Access

Security Best Practices

1. Never Commit Secrets

2. Use Environment-Specific Configuration

3. Rotate Keys Regularly

4. Use Restricted Keys

5. Monitor Usage

6. Use Secret Management in Production

Troubleshooting

”API key not set” Error

“Invalid API key” Error

”Rate limit exceeded” Error

”Insufficient quota” Error

Cost Optimization

1. Use Stub Mode for Development

2. Choose Appropriate Models

3. Cache Compiled IR

4. Monitor Token Usage

Related Documentation