Security

How AgentKavach protects your data, authenticates requests, and secures integrations.

Transport Security #

All communication with the AgentKavach API is encrypted using TLS 1.2 or higher. Plain HTTP connections are rejected. The SDK enforces HTTPS for all outbound requests to the AgentKavach backend.

Authentication #

AgentKavach supports two authentication methods:

JWT Tokens (Dashboard)

The dashboard uses short-lived JWT tokens issued on login. Tokens are passed in the Authorization header as a Bearer token. Refresh tokens are stored in HTTP-only cookies.

API Keys (SDK)

The SDK authenticates with API keys that start with the cg_ prefix. Keys are passed in the Authorization header as a Bearer token — never in URL query parameters or request bodies.

Authorization: Bearer cg_your_api_key_here

Authorization #

API keys are scoped per organization. Each key can only access data belonging to its organization. Role-based access control (RBAC) governs dashboard permissions:

• Owner — Full access including billing, team management, and API key rotation.
• Admin — Manage agents, budgets, and alert rules. Cannot modify billing.
• Member — View-only access to dashboards and spend data.

Input Validation #

All API inputs are validated against strict schemas using Pydantic models. The backend uses parameterized queries for all database operations — no string interpolation or raw SQL. Request payloads that fail validation return a 422 Validation Error with details about which fields are invalid.

Rate Limiting #

Rate limiting is enforced per API key using a Redis-backed sliding window. Two layers of limits apply:

• Daily event limit — Maximum number of events per day, based on your subscription tier.
• Burst rate limit — Maximum events per second to prevent abuse.

Additionally, a global IP-based rate limit of 10,000 requests/second applies across all API keys from the same IP address. This prevents DDoS abuse regardless of subscription tier.

Organization owners can request custom rate limit overrides via the admin API. Overrides take precedence over tier defaults for both daily and burst limits.

When rate limited, the API returns 429 Too Many Requests with a resume_at field indicating when the limit resets. The SDK handles this gracefully — it logs a warning but does not block your LLM calls (fail-open design).

HMAC Webhook Signing #

All webhook payloads are signed with HMAC-SHA256 using your webhook secret. The signature is included in the X-AgentKavach-Signature header. Always verify the signature before processing webhook events.

Verification Example

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify an AgentKavach webhook signature."""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
signature = request.headers["X-AgentKavach-Signature"]
body = request.body  # raw bytes

if not verify_webhook(body, signature, WEBHOOK_SECRET):
    raise ValueError("Invalid webhook signature")

Secrets Management #

All secrets and credentials must be stored in environment variables or .env files — never committed to source code or version control. The .env file is included in .gitignore by default.

AgentKavach configuration uses environment variables prefixed with AGENTKAVACH_:

# .env file — never commit this
AGENTKAVACH_API_KEY=cg_your_key_here
AGENTKAVACH_DB_URL=postgresql://user:pass@host:5432/db
AGENTKAVACH_REDIS_URL=redis://host:6379/0
AGENTKAVACH_JWT_SECRET=your-jwt-secret
AGENTKAVACH_WEBHOOK_SECRET=your-webhook-secret