Credential Management

Anvil includes a credential management system that helps handle missing API keys gracefully, with optional interactive prompting.

The Problem

Tools often fail because of missing credentials:

tool.run(query="test")
# Error: NOTION_API_KEY environment variable not set

Anvil can detect these errors and help resolve them.

Enabling Interactive Credentials

anvil = Anvil(
    interactive_credentials=True,  # Enable prompting
    env_file=".env",               # Where to save credentials
)

When a tool fails due to a missing credential, Anvil will:

Detect the missing key from the error message
Prompt you to enter it
Optionally save it to your .env file
Retry the tool execution

How Detection Works

Anvil looks for common patterns in error messages:

# These patterns are detected:
"NOTION_API_KEY not set"
"Missing environment variable: GITHUB_TOKEN"
"API key not found"
"Authentication failed: no key provided"

The credential name is extracted and you’re prompted to provide it.

Known API Keys

Anvil has built-in knowledge of common API keys:

Key Name	Service	Get Key URL
`ANTHROPIC_API_KEY`	Claude	console.anthropic.com
`OPENAI_API_KEY`	OpenAI	platform.openai.com
`FIRECRAWL_API_KEY`	FireCrawl	firecrawl.dev
`NOTION_API_KEY`	Notion	notion.so/my-integrations
`GITHUB_TOKEN`	GitHub	github.com/settings/tokens
`SLACK_BOT_TOKEN`	Slack	api.slack.com/apps

When prompting for these keys, Anvil shows helpful information:

🔑 Missing credential: NOTION_API_KEY

  Notion API Key
  Get yours at: https://www.notion.so/my-integrations

  Enter value (or press Enter to skip):

Saving Credentials

When you enter a credential, Anvil offers to save it:

Save to .env file? [y/N]: y
✓ Saved NOTION_API_KEY to .env

The credential is appended to your .env file:

# Existing keys...
ANTHROPIC_API_KEY=sk-ant-...

# Added by Anvil
NOTION_API_KEY=secret_...

Session Cache

Entered credentials are cached for the session:

# First call - prompts for NOTION_API_KEY
tool1.run(query="test")

# Second call - uses cached value, no prompt
tool2.run(query="test")

# Clear the cache
anvil.credential_resolver.clear_session_cache()

Programmatic Access

Access the credential resolver directly:

resolver = anvil.credential_resolver

# Check if a key is known
info = resolver.get_key_info("NOTION_API_KEY")
print(info["url"])  # https://www.notion.so/my-integrations

# Manually prompt for a credential
value = resolver.prompt_for_credential("CUSTOM_API_KEY")

# Detect missing credential from error
error_msg = "CUSTOM_KEY not set"
key_name = resolver.detect_missing_credential(error_msg)
print(key_name)  # "CUSTOM_KEY"

Disabling Interactive Mode

For CI/CD or automated environments:

# Disable interactive prompts
anvil = Anvil(interactive_credentials=False)

# Credentials must be in environment or .env file
# Missing credentials will raise errors

Custom .env File

Specify a custom location for your environment file:

anvil = Anvil(
    env_file="/path/to/custom/.env",
    interactive_credentials=True,
)

Security Best Practices

1. Never Commit .env Files

Ensure .env is in your .gitignore:

anvil init  # Automatically adds .env to .gitignore

2. Use Environment Variables in Production

# Production
export ANTHROPIC_API_KEY="sk-ant-..."
export NOTION_API_KEY="secret_..."

# Anvil reads from environment
anvil = Anvil()  # No .env file needed

3. Rotate Keys Regularly

If a key is compromised:

Revoke the old key at the provider
Generate a new key
Update your .env or environment variables

4. Use Scoped Keys

When possible, use API keys with minimal permissions:

GitHub: Use fine-grained tokens with specific repo access
Notion: Create integrations with limited workspace access
Slack: Use bot tokens with minimal scopes

Credential Resolution Flow

┌─────────────────┐
│  Tool Executes  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│    Success?     │─Yes─▶│  Return Result  │
└────────┬────────┘     └─────────────────┘
         │No
         ▼
┌─────────────────┐     ┌─────────────────┐
│ Credential      │─No──▶│  Raise Error    │
│ Error Detected? │     └─────────────────┘
└────────┬────────┘
         │Yes
         ▼
┌─────────────────┐     ┌─────────────────┐
│ Interactive     │─No──▶│  Raise Error    │
│ Mode Enabled?   │     └─────────────────┘
└────────┬────────┘
         │Yes
         ▼
┌─────────────────┐
│ Prompt User for │
│   Credential    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Cache & Retry  │
└─────────────────┘