Authentication - Agentic Wallet

Overview

The Agentic Wallet API uses API key-based authentication with scope-based access control. All requests must include a valid API key in the request headers.

API Key Header

Include your API key in every request:

string

required

Your API key for authentication

curl -H "x-api-key: your-api-key-here" \
     http://localhost:3000/api/v1/wallets

Tenant Header

For multi-tenant deployments, specify the tenant:

string

Tenant identifier. Use * for wildcard access (if permitted by your API key).

curl -H "x-api-key: your-api-key-here" \
     -H "x-tenant-id: tenant-123" \
     http://localhost:3000/api/v1/wallets

Configuration

API keys are configured via environment variables:

Enable/Disable Authentication

API_GATEWAY_ENFORCE_AUTH=true  # Set to false to disable auth (development only)

API Key Format

API keys follow the format:

key:tenant:scope1,scope2,scope3

Multiple keys separated by semicolons:

API_GATEWAY_API_KEYS="dev-api-key:*:all;prod-key:tenant-1:wallets,transactions"

Components:

key: The actual API key string
tenant: Tenant ID or * for all tenants
scopes: Comma-separated list of scopes or all for full access

Scopes

The following scopes control access to API resources:

Resource Scopes
Examples

Scope	Description
`wallets`	Create and manage wallets
`transactions`	Create and manage transactions
`policies`	Create and evaluate policies
`agents`	Create and manage agents
`protocols`	Access protocol adapters
`risk`	Manage risk configurations
`strategy`	Backtest and paper trading
`treasury`	Treasury allocation operations
`audit`	Access audit events and metrics
`mcp`	MCP tool access
`all`	Full access to all resources

Development key with full access:

dev-api-key:*:all

Production key with limited scopes:

prod-key-abc123:tenant-1:wallets,transactions,policies

Read-only audit key:

audit-key-xyz789:*:audit

Agent execution key:

agent-key-def456:tenant-2:wallets,transactions,agents,protocols

Example Configurations

Development Setup

API_GATEWAY_ENFORCE_AUTH=true
API_GATEWAY_API_KEYS="dev-api-key:*:all"
API_GATEWAY_RATE_LIMIT_PER_MINUTE=120

Production Multi-Tenant

API_GATEWAY_ENFORCE_AUTH=true
API_GATEWAY_API_KEYS="prod-key-1:tenant-a:wallets,transactions;prod-key-2:tenant-b:all;admin-key:*:all"
API_GATEWAY_RATE_LIMIT_PER_MINUTE=60

Rate Limiting

Rate limits are applied per API key:

API_GATEWAY_RATE_LIMIT_PER_MINUTE=120  # Default: 120 requests/minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1709899260

Error Responses

Missing API Key

curl http://localhost:3000/api/v1/wallets

Response (401 Unauthorized):

{
  "status": "failure",
  "errorCode": "VALIDATION_ERROR",
  "failedAt": "gateway",
  "stage": "gateway",
  "error": "Missing x-api-key header"
}

Invalid API Key

curl -H "x-api-key: invalid-key" \
     http://localhost:3000/api/v1/wallets

Response (401 Unauthorized):

{
  "status": "failure",
  "errorCode": "VALIDATION_ERROR",
  "failedAt": "gateway",
  "stage": "gateway",
  "error": "Invalid API key"
}

Insufficient Scope

curl -H "x-api-key: limited-key" \
     http://localhost:3000/api/v1/policies

Response (403 Forbidden):

{
  "status": "failure",
  "errorCode": "VALIDATION_ERROR",
  "failedAt": "gateway",
  "stage": "gateway",
  "error": "Insufficient scope: requires 'policies'"
}

Rate Limit Exceeded

Response (429 Too Many Requests):

{
  "status": "failure",
  "errorCode": "VALIDATION_ERROR",
  "failedAt": "gateway",
  "stage": "gateway",
  "error": "Rate limit exceeded"
}

Security Best Practices

Never expose API keys in client-side code, version control, or public repositories.

Use environment variables or secure secret management systems to store API keys.

Recommendations:

Use separate API keys for different environments (dev, staging, production)
Apply principle of least privilege - grant only required scopes
Rotate API keys regularly
Monitor API key usage via audit logs
Use tenant-specific keys for multi-tenant deployments
Set appropriate rate limits based on usage patterns

Testing Authentication

Verify your API key works:

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-03-08T12:00:00.000Z"
}

​Overview

​API Key Header

​Tenant Header

​Configuration

​Enable/Disable Authentication

​API Key Format

​Scopes

​Example Configurations

​Development Setup

​Production Multi-Tenant

​Rate Limiting

​Error Responses

​Missing API Key

​Invalid API Key

​Insufficient Scope

​Rate Limit Exceeded

​Security Best Practices

​Testing Authentication

Overview

API Key Header

Tenant Header

Configuration

Enable/Disable Authentication

API Key Format

Scopes

Example Configurations

Development Setup

Production Multi-Tenant

Rate Limiting

Error Responses

Missing API Key

Invalid API Key

Insufficient Scope

Rate Limit Exceeded

Security Best Practices

Testing Authentication