The @agentdoor/core configuration system uses Zod for runtime validation with strict type safety. This reference covers the complete AgentDoorConfig schema and all available options.
AgentDoorConfig The main configuration object passed to AgentDoor initialization.
import { AgentDoorConfig } from "@agentdoor/core" ; const config : AgentDoorConfig = { scopes: [ { id: "weather.read" , description: "Read weather data" , price: "$0.001/req" , rateLimit: "1000/hour" } ], storage: { driver: "sqlite" , url: "./agentdoor.db" }, x402: { network: "base" , currency: "USDC" , paymentAddress: "0x..." } };
Required Fields scopes
ScopeDefinition[]
required
Array of available scopes that agents can request. At least one scope must be defined. Show ScopeDefinition properties
Unique scope identifier. Must start with a letter and contain only letters, digits, underscores, and dots. Example: "weather.read", "api.v1.users"
Human-readable description of what this scope grants. Example: "Read weather forecast data"
Pricing string for this scope. Example: "$0.001/req", "$5.00/month"
Scope-specific rate limit override. Example: "1000/hour", "100/day"
Storage Configuration Storage backend configuration. Defaults to in-memory storage. Show StorageConfig properties
driver
'memory' | 'sqlite' | 'postgres' | 'redis'
required
Storage driver to use.
memory: In-memory storage (development only)sqlite: SQLite database (single-process)postgres: PostgreSQL database (multi-process)redis: Redis storage (distributed) Connection URL for database-backed stores. Examples:
SQLite: "./agentdoor.db"
Postgres: "postgresql://user:pass@localhost/agentdoor"
Redis: "redis://localhost:6379"
Additional driver-specific options.
Rate Limiting Default rate limit applied to new agents. Defaults to 1000 requests per hour. Show RateLimitConfig properties
Maximum number of requests in the window. Must be a positive integer.
Time window string. Format: {number}{unit} where unit is:
s: secondsm: minutesh: hoursd: days Examples: "1h", "30m", "1d" Rate limit for the registration endpoint itself. Defaults to 10 registrations per hour.
x402 Payment Protocol x402 payment protocol configuration. If not provided, payment features are disabled. Show X402Config properties
Blockchain network. Common values: "base", "solana", "ethereum"
Payment currency. Example: "USDC", "ETH"
Your wallet address for receiving payments.
x402 facilitator URL. Defaults to https://x402.org/facilitator
JWT Configuration JWT token settings for agent authentication. Show JwtConfig properties
HMAC secret for JWT signing. Must be at least 16 characters. Auto-generated if not provided.
Token expiration duration. Format: {number}{unit}. Defaults to "1h". Examples: "1h", "24h", "7d"
Cryptographic Signing Cryptographic signing algorithm configuration. Show SigningConfig properties
algorithm
'ed25519' | 'secp256k1'
required
Signature algorithm. Defaults to "ed25519".
ed25519: Fast, modern, recommendedsecp256k1: Bitcoin/Ethereum-compatible Service metadata for discovery documents. Show ServiceConfig properties
Service name. Defaults to "AgentDoor Service"
Service description. Defaults to "An AgentDoor-enabled API service"
URL to API documentation. Must be a valid URL.
Support email address. Must be a valid email.
Companion Protocols Auto-generate endpoints for companion protocols. Show CompanionConfig properties
Auto-generate /.well-known/agent-card.json for A2A protocol. Defaults to true.
Auto-generate /mcp endpoint. Defaults to false.
Expose OAuth 2.1 compatibility endpoints for MCP clients. Defaults to false.
Other Configuration Global pricing map. Scope ID to price string. Example: { "weather.read": "$0.001/req" }
Challenge expiry duration in seconds. Defaults to 300 (5 minutes).
API key mode. Affects the prefix of generated API keys.
live: Keys prefixed with agk_live_test: Keys prefixed with agk_test_ Defaults to "live". Callbacks onAgentRegistered
(agent: Agent) => void | Promise<void>
Callback invoked when an agent successfully completes registration. onAgentRegistered : async ( agent ) => { console . log ( `Agent registered: ${ agent . id } ` ); await notifySlack ( `New agent: ${ agent . metadata . name } ` ); }
onAgentAuthenticated
(agent: Agent) => void | Promise<void>
Callback invoked when an agent successfully authenticates. onAgentAuthenticated : async ( agent ) => { console . log ( `Agent authenticated: ${ agent . id } ` ); await updateMetrics ( agent . id ); }
Validation Functions validateConfig Validates an AgentDoorConfig object against the Zod schema.
import { validateConfig } from "@agentdoor/core" ; const config = { /* ... */ }; const validated = validateConfig ( config );
Configuration object to validate.
The validated configuration object.
Throws: InvalidConfigError if validation fails with detailed error messages.try { validateConfig ({ scopes: [] }); // Invalid: empty scopes } catch ( error ) { console . error ( error . message ); // "Configuration validation failed: // - scopes: At least one scope must be defined" }
resolveConfig Validates and resolves an AgentDoorConfig, applying all default values.
import { resolveConfig } from "@agentdoor/core" ; const config = { scopes: [{ id: "api.read" , description: "Read API" }] }; const resolved = resolveConfig ( config ); // Returns ResolvedConfig with all defaults applied: // - storage: { driver: "memory" } // - rateLimit: { requests: 1000, window: "1h" } // - jwt.secret: auto-generated // - etc.
Configuration object to resolve.
Configuration with all defaults applied. No optional fields (except x402).
Configuration Examples Minimal Configuration const config : AgentDoorConfig = { scopes: [ { id: "api.read" , description: "Read access" } ] };
Production Configuration const config : AgentDoorConfig = { scopes: [ { id: "weather.read" , description: "Read weather forecast data" , price: "$0.001/req" , rateLimit: "5000/hour" }, { id: "weather.write" , description: "Submit weather observations" , price: "$0.005/req" , rateLimit: "100/hour" } ], storage: { driver: "postgres" , url: process . env . DATABASE_URL }, x402: { network: "base" , currency: "USDC" , paymentAddress: process . env . WALLET_ADDRESS ! , facilitator: "https://x402.org/facilitator" }, rateLimit: { requests: 10000 , window: "1h" }, jwt: { secret: process . env . JWT_SECRET , expiresIn: "24h" }, service: { name: "Weather API" , description: "Professional weather data for AI agents" , docsUrl: "https://api.weather.com/docs" , supportEmail: "[email protected] " }, mode: "live" , onAgentRegistered : async ( agent ) => { await analytics . track ( "agent_registered" , { agentId: agent . id , scopes: agent . scopesGranted }); } };
Development Configuration const config : AgentDoorConfig = { scopes: [ { id: "api.read" , description: "Read access" }, { id: "api.write" , description: "Write access" } ], storage: { driver: "memory" }, mode: "test" , rateLimit: { requests: 100000 , window: "1h" } };