Agent API Keys

Key Use Cases

Agent API Keys enable powerful automation and integration scenarios that require autonomous agent access.

The Authentication Gap

Deployment-Time Generation

Agent API Keys can be pre-configured during agent deployment using the app manifest or CLI options:

Via App Manifest (Planned Feature)

Future capability to define agent key permissions directly in your app_manifest.yml:

# app_manifest.yml
app:
  name: "Advanced Chat Agent"
  version: "2.0.0"

agents:
  - name: "chatAgent"
    description: "Main chat processing agent"
    agent_type_id: "llm"
    
    # Agent API Key configuration
    api_key:
      generate: true
      name: "Chat Agent Production Key"
      scopes:
        - "agent:activate"
        - "activations:read"
        - "activations:write"
        - "data:read"
        - "data:write"
        - "webhooks:manage"
      expires_after: "90d"  # Optional expiration
      environment: "production"  # Optional environment tag
      
  - name: "analyticsAgent"
    description: "Analytics and reporting agent"
    agent_type_id: "data-processing"
    
    api_key:
      generate: true
      name: "Analytics Agent Key"
      scopes:
        - "agent:activate"
        - "activations:read"
        - "data:read"  # Read-only for analytics
      expires_after: "30d"

Via CLI Options (Planned Feature)

# Future: Deploy agent with specific API key scope
fiber deploy agent ./my-agent --scope="read:activations,write:data" --api-key-name="Production Agent Key"

# Current: Agent keys are generated with full access by default
✅ Agent deployed successfully
🔑 Agent API Key generated: agent_key_xyz789...
📋 Scope: full_agent_access (default)
💾 Key stored for agent: my-agent-v1.0.0

End Value & Benefits

Agent API Keys unlock autonomous AI workflows and seamless system integrations that scale beyond manual operations.

Real-World Example

# Automated daily report generation
curl -X POST "http://localhost:8000/api/v1/agents/report-generator/activate" \
  -H "Authorization: Bearer agent_key_reports_xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {
      "report_type": "daily_metrics",
      "date_range": "yesterday"
    },
    "context_type": "scheduled_task"
  }'

# Webhook-triggered agent activation from external system
curl -X POST "http://localhost:8000/api/v1/agents/customer-support/activate" \
  -H "Authorization: Bearer agent_key_support_abc..." \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {
      "ticket_id": "TICKET-123",
      "customer_message": "I need help with my account"
    },
    "context_type": "webhook_trigger"
  }'

Planned Scopes & Features

The Agent API Key system is designed for future expansion with granular permission scopes and advanced capabilities.

🚧 Planned Permission Scopes

🔮 Planned Advanced Features

# Generate time-limited key
fiber agent generate-key my-agent --expires="24h" --auto-refresh

# Response
🔑 Agent API Key: agent_key_temp_123...
⏰ Expires: 2024-01-02T12:00:00Z
🔄 Auto-refresh: enabled

# Multi-agent key for workflow
fiber agent generate-key workflow-suite \
  --agents="preprocessor,analyzer,reporter" \
  --scope="agent:activate,data:read"

# View key usage statistics
fiber agent key-stats my-agent

# Response
📈 Activations: 1,234 (last 30 days)
🕐 Peak usage: 14:00-16:00 UTC
🌍 Geographic distribution: US (60%), EU (30%), APAC (10%)
⚡ Average response time: 2.3s

# Environment-specific keys
fiber agent generate-key my-agent --environment="production" --scope="full"
fiber agent generate-key my-agent --environment="staging" --scope="limited"
fiber agent generate-key my-agent --environment="development" --scope="debug"

Key Management

Current and planned capabilities for managing Agent API Keys throughout their lifecycle.

Current Management

# List agent keys (current capability)
curl -X GET "http://localhost:8000/api/v1/agents/my-agent/api-keys" \
  -H "Authorization: Bearer user_api_key..."

# Response
{
  "keys": [
    {
      "id": "key_123",
      "name": "Auto-generated",
      "created_at": "2024-01-01T00:00:00Z",
      "scope": "default",
      "last_used": "2024-01-01T12:00:00Z"
    }
  ]
}

🚧 Planned Management Features

# Rotate agent key
fiber agent rotate-key my-agent --grace-period="1h"

✅ New key generated: agent_key_new_456...
⏰ Old key valid until: 2024-01-01T13:00:00Z
🔄 Rotation complete

# Revoke compromised key
fiber agent revoke-key my-agent key_123 --reason="compromised"

# Suspend key temporarily
fiber agent suspend-key my-agent key_123 --duration="2h"

{
  "event": "key_used",
  "agent_id": "my-agent",
  "key_id": "key_123",
  "action": "agent:activate",
  "timestamp": "2024-01-01T12:00:00Z",
  "ip_address": "192.168.1.100",
  "user_agent": "FiberSDK/1.0.0",
  "result": "success"
}

Security Considerations

Best Practices

• Never log Agent API Keys in application logs or error messages
• Use environment variables to store keys in production applications
• Rotate keys regularly (planned feature) for enhanced security
• Monitor key usage for unusual patterns or unauthorized access
• Revoke unused keys to minimize attack surface

Manifest-Based Configuration

The app_manifest.yml file provides declarative configuration for Agent API Keys, making permissions explicit and version-controlled.

Complete Manifest Example

# app_manifest.yml - Complete agent key configuration
app:
  name: "Multi-Agent Workspace"
  version: "1.0.0"
  description: "Collaborative AI workspace with specialized agents"

agents:
  - name: "orchestratorAgent"
    description: "Main orchestration agent"
    agent_type_id: "llm"
    
    api_key:
      generate: true
      name: "Orchestrator Master Key"
      scopes:
        - "agent:activate"
        - "agent:read"
        - "activations:read"
        - "activations:write"
        - "activations:stream"
        - "data:read"
        - "data:write"
        - "data:query"
        - "functions:invoke"
        - "webhooks:manage"
        - "credentials:use"
      expires_after: "365d"
      environment: "production"
      auto_rotate: true
      rotation_interval: "90d"
      
  - name: "dataProcessor" 
    description: "Data analysis and processing agent"
    agent_type_id: "data-processing"
    
    api_key:
      generate: true
      name: "Data Processor Key"
      scopes:
        - "agent:activate"
        - "activations:read"
        - "data:read"
        - "data:write"
        - "data:query"
        - "functions:invoke"
      expires_after: "180d"
      environment: "production"
      
  - name: "notificationAgent"
    description: "Handles notifications and alerts"
    agent_type_id: "notification"
    
    api_key:
      generate: true
      name: "Notification Agent Key"
      scopes:
        - "agent:activate"
        - "activations:read"
        - "webhooks:manage"
        - "credentials:use"  # For email/slack integrations
      expires_after: "90d"
      
  - name: "readOnlyReporter"
    description: "Read-only reporting agent"
    agent_type_id: "reporting"
    
    api_key:
      generate: true
      name: "Reporter Read-Only Key"
      scopes:
        - "agent:activate"
        - "activations:read"
        - "data:read"
        - "data:query"
      expires_after: "30d"
      environment: "reporting"

Deployment with Manifest

# Deploy app with agent key configuration
fiber install app ./multi-agent-workspace --verbose

# Output shows generated keys
✅ App installed: Multi-Agent Workspace v1.0.0
🔑 Generated Agent API Keys:
   • orchestratorAgent: agent_key_orch_abc123... (12 scopes, expires 365d)
   • dataProcessor: agent_key_data_def456... (6 scopes, expires 180d)  
   • notificationAgent: agent_key_notif_ghi789... (4 scopes, expires 90d)
   • readOnlyReporter: agent_key_report_jkl012... (4 scopes, expires 30d)

💾 Keys stored and ready for use
📋 Check key details: fiber agent list-keys --app-id multi-agent-workspace

Manifest Schema Reference

Environment-Specific Configuration

Use different manifest configurations for different environments:

# app_manifest.production.yml
agents:
  - name: "mainAgent"
    api_key:
      generate: true
      name: "Production Agent Key"
      scopes: ["agent:activate", "data:read", "data:write"]
      expires_after: "365d"
      environment: "production"
      auto_rotate: true

# app_manifest.development.yml  
agents:
  - name: "mainAgent"
    api_key:
      generate: true
      name: "Development Agent Key"
      scopes: ["agent:activate", "data:read", "data:write", "debug:access"]
      expires_after: "7d"
      environment: "development"

Integration Examples

Python SDK Integration

from fiberwise_sdk import FiberApp

# Using agent-specific key for focused access
app = FiberApp({
    'api_key': 'agent_key_abc123...',  # Agent API key, not user API key
    'base_url': 'https://api.fiberwise.ai/api/v1',
    'app_id': 'your-app-id'
})

# This will work - agent can activate itself
result = await app.agents.execute("my-agent", request)

# This will fail - agent key cannot access other agents
try:
    other_result = await app.agents.execute("different-agent", request)
except AuthenticationError:
    print("Agent API key cannot access other agents")

Webhook Integration

// Webhook endpoint using agent API key
app.post('/webhook/agent-callback', async (req, res) => {
  const agentApiKey = process.env.AGENT_API_KEY;
  
  // Use agent key for secure callback
  const response = await fetch('http://localhost:8000/api/v1/agents/my-agent/activate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${agentApiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input_data: req.body,
      context_type: 'webhook'
    })
  });
  
  res.json({ status: 'processed' });
});

🗺️ Development Roadmap