Agent-Key Authentication

Authenticate AI agents using Agent-Key headers with service-scoped access control

Overview

Agent-Key authentication is designed for AI agents making API calls to protected services. Each agent has a unique API key that can be scoped to specific services.

How It Works

Agent keys are validated by the requireAgentAuth middleware in /home/daytona/workspace/source/backend/src/middleware/auth.ts:65:

1. Extract Agent-Key header from request
2. Validate key format (must start with agt_)
3. Hash the key and lookup in database
4. Check if agent is active
5. Return agent ID and user ID

Authentication Flow

Using Agent-Key in Requests

Header Format

Include the Agent-Key header in every request to protected endpoints:

curl https://api.example.com/proxy/service-123 \
  -H "Agent-Key: agt_1234567890abcdef1234567890abcdef"

Agent-Key · string · required

Your agent’s API key. Must start with agt_ prefix.

Service-Based Access Control

Agent keys are scoped to specific services via the agent_services join table. The requireServiceAccess middleware checks authorization:

// From middleware/auth.ts:112
export async function requireServiceAccess(
  agentId: number, 
  serviceId: number
): Promise<void>

Access Check Flow

1. Agent authenticates with Agent-Key
2. Request targets a specific service
3. System checks agent_services table for relationship
4. Returns 403 Forbidden if agent lacks access

Creating Agent Keys

Agent keys are created via the dashboard API (requires JWT authentication):

Create Agent

cURL

curl -X POST https://api.gaiterguard.com/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Agent",
    "serviceIds": [1, 2, 3]
  }'

{
  "agent": {
    "id": 42,
    "name": "Production Agent",
    "userId": 10,
    "keyPreview": "agt_...cdef",
    "isActive": true,
    "createdAt": "2026-03-03T10:00:00Z",
    "lastUsedAt": null
  },
  "apiKey": "agt_1234567890abcdef1234567890abcdef",
  "services": [
    {"id": 1, "name": "OpenAI GPT-4"},
    {"id": 2, "name": "Anthropic Claude"},
    {"id": 3, "name": "Database API"}
  ]
}

The full apiKey is only returned once during creation. Store it securely - it cannot be retrieved again.

Request Body

name · string · required

Human-readable name for the agent (e.g., “Production Bot”, “Staging Agent”)

serviceIds · number[] · required

Array of service IDs this agent can access. Pass an empty array [] for no service access.

Response Fields

agent · object

The created agent record

id · number

Unique agent identifier

name · string

Agent name

keyPreview · string

Truncated key for identification (e.g., agt_...cdef)

isActive · boolean

Whether the agent key is active. Defaults to true.

lastUsedAt · string | null

ISO timestamp of last API usage. null if never used.

apiKey · string

Full API key - only returned during creation. Store this securely.

services · array

List of services this agent can access

Managing Agent Keys

List All Agents

curl https://api.gaiterguard.com/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Agent Services

Change which services an agent can access:

curl -X PUT https://api.gaiterguard.com/agents/42/services \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceIds": [1, 3, 5]
  }'

Revoke Agent Key

Set isActive to false to revoke access:

curl -X PUT https://api.gaiterguard.com/agents/42 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Delete Agent

Permanently delete an agent and all service associations:

curl -X DELETE https://api.gaiterguard.com/agents/42 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Error Responses

Missing Agent-Key Header

{
  "error": "Missing Agent-Key header",
  "statusCode": 401
}

Invalid Key Format

{
  "error": "Invalid Agent-Key format",
  "statusCode": 401
}

Agent keys must start with agt_ prefix.

Invalid or Revoked Key

{
  "error": "Invalid Agent-Key",
  "statusCode": 401
}

Returned when:

• Key doesn’t exist in database
• Agent’s isActive is false

Insufficient Service Access

{
  "error": "Agent does not have access to this service",
  "statusCode": 403
}

The agent key is valid but not authorized for the requested service.

Security Best Practices

Store Keys Securely

• Use environment variables or secret managers
• Never commit keys to version control
• Rotate keys if exposed

Scope Agent Access

• Only grant access to required services
• Create separate agents for different environments
• Use descriptive names for easy identification

Monitor Usage

• Check lastUsedAt timestamps regularly
• Revoke unused agents
• Review service access periodically

Implementation Reference

Source code locations:

• Agent authentication middleware: backend/src/middleware/auth.ts:65
• Service access check: backend/src/middleware/auth.ts:112
• Agent management routes: backend/src/routes/agents.ts
• Key hashing utility: backend/src/utils/apikey.ts