Skip to main content
info

This documentation is automatically synchronized from the claude-hub repository. Last updated: 2025-06-01

Claude Authentication Guide

This guide covers three authentication methods for using Claude with the webhook service.

Authentication Methods Overview​

MethodUse CaseSetup Complexity
Setup ContainerPersonal developmentMedium
ANTHROPIC_API_KEYProduction environmentsLow
AWS BedrockEnterprise integrationHigh

🐳 Option 1: Setup Container (Personal Development)​

Uses personal Claude Code subscription for authentication.

Setup Process​

1. Run Interactive Authentication Setup​

./scripts/setup/setup-claude-interactive.sh

2. Authenticate in Container​

When the container starts:

# In the container shell:
claude --dangerously-skip-permissions  # Follow authentication flow
exit                                   # Save authentication state

3. Test Captured Authentication​

./scripts/setup/test-claude-auth.sh

4. Use Captured Authentication​

# Option A: Copy to your main Claude directory
cp -r ${CLAUDE_HUB_DIR:-~/.claude-hub}/* ~/.claude/

# Option B: Mount in docker-compose
# Update docker-compose.yml:
# - ./${CLAUDE_HUB_DIR:-~/.claude-hub}:/home/node/.claude

5. Verify Setup​

node cli/webhook-cli.js --repo "owner/repo" --command "Test authentication" --url "http://localhost:8082"

Troubleshooting​

  • Tokens expire: Re-run authentication setup when needed
  • File permissions: Ensure .credentials.json is readable by container user
  • Mount issues: Verify correct path in docker-compose volume mounts

🔑 Option 2: ANTHROPIC_API_KEY (Production)​

Direct API key authentication for production environments.

Setup Process​

1. Get API Key​

  1. Go to Anthropic Console
  2. Create a new API key
  3. Copy the key (starts with sk-ant-)

2. Configure Environment​

# Add to .env file
ANTHROPIC_API_KEY=sk-ant-your-api-key-here

3. Restart Service​

docker compose restart webhook

4. Test​

node cli/webhook-cli.js --repo "owner/repo" --command "Test API key authentication" --url "http://localhost:8082"

Best Practices​

  • Key rotation: Regularly rotate API keys
  • Environment security: Never commit keys to version control
  • Usage monitoring: Monitor API usage through Anthropic Console

☁️ Option 3: AWS Bedrock (Enterprise)​

AWS-integrated Claude access for enterprise deployments.

Setup Process​

1. Configure AWS Credentials​

# Option A: AWS Profile (Recommended)
./scripts/aws/setup-aws-profiles.sh

# Option B: Environment Variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

2. Configure Bedrock Settings​

# Add to .env file
CLAUDE_CODE_USE_BEDROCK=1
ANTHROPIC_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
AWS_REGION=us-east-1

# If using profiles
USE_AWS_PROFILE=true
AWS_PROFILE=claude-webhook

3. Verify Bedrock Access​

aws bedrock list-foundation-models --region us-east-1

4. Restart Service​

docker compose restart webhook

5. Test​

node cli/webhook-cli.js --repo "owner/repo" --command "Test Bedrock authentication" --url "http://localhost:8082"

Best Practices​

  • IAM policies: Use minimal required permissions
  • Regional selection: Choose appropriate AWS region
  • Access logging: Enable CloudTrail for audit compliance

🚀 Authentication Priority and Fallback​

The system checks authentication methods in this order:

  1. ANTHROPIC_API_KEY (highest priority)
  2. Claude Interactive Authentication (setup container)
  3. AWS Bedrock (if configured)

Environment Variables​

# Method 1: Direct API Key
ANTHROPIC_API_KEY=sk-ant-your-key

# Method 2: Claude Interactive (automatic if ~/.claude is mounted)
# No environment variables needed

# Method 3: AWS Bedrock
CLAUDE_CODE_USE_BEDROCK=1
ANTHROPIC_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_key_id
AWS_SECRET_ACCESS_KEY=your_secret_key
# OR
USE_AWS_PROFILE=true
AWS_PROFILE=your-profile-name

🛠️ Switching Between Methods​

You can switch between authentication methods by updating your .env file:

# Development with personal subscription
# Comment out API key, ensure ~/.claude is mounted
# ANTHROPIC_API_KEY=
# Mount: ~/.claude:/home/node/.claude

# Production with API key
ANTHROPIC_API_KEY=sk-ant-your-production-key

# Enterprise with Bedrock
CLAUDE_CODE_USE_BEDROCK=1
ANTHROPIC_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
USE_AWS_PROFILE=true
AWS_PROFILE=production-claude

🔍 Troubleshooting​

Authentication Not Working​

  1. Check environment variables are set correctly
  2. Verify API keys are valid and not expired
  3. For Bedrock: Ensure AWS credentials have correct permissions
  4. For setup container: Re-run authentication if tokens expired

Rate Limiting​

  • API Key: Contact Anthropic for rate limit information
  • Bedrock: Configure AWS throttling settings
  • Setup Container: Limited by subscription tier

📚 Additional Resources​

This guide covers all authentication methods for the Claude GitHub Webhook service. Choose the method that best fits your technical requirements.