AuthzX Agent

Lightweight authorization sidecar for AI agents, APIs, and microservices.

Open-source. Self-hostable. No vendor lock-in.

The AuthzX Agent runs alongside your services and makes authorization decisions locally with sub-millisecond latency. It pulls policies from AuthzX Cloud (or loads them from a local file), evaluates requests against the authorization engine in-memory, and returns allow/deny decisions without network round-trips on the hot path.

What it does

• Serves POST /access/v1/evaluation with sub-millisecond decision latency — no per-request calls to the cloud
• Syncs policy bundles automatically from AuthzX Cloud on a configurable interval
• Caches bundles to disk for instant warm restarts (no downtime during deploys or cloud outages)
• Exposes Prometheus metrics, structured decision logs, and health endpoints out of the box

Quick Start

Install

Docker (recommended):

docker pull authzx/agent:latest

Go install:

go install github.com/authzx/agent/cmd/agent@latest

Binary download:

Grab the latest release from GitHub Releases for your platform (linux/amd64, linux/arm64, darwin/arm64).

Configure

Create authzx-agent.yml (or set environment variables):

api_key: "your-authzx-api-key"
cloud_url: "https://api.authzx.com"
listen_addr: "0.0.0.0:8181"
poll_interval: "30s"

Run

# With config file
authzx-agent --config ./authzx-agent.yml

# With env vars
AUTHZX_API_KEY=your-key authzx-agent

# With Docker
docker run -d \
  -e AUTHZX_API_KEY=your-key \
  -p 8181:8181 \
  -v authzx-cache:/var/lib/authzx/bundles \
  authzx/agent:latest

Test with curl

# Allowed request
curl -s -X POST http://localhost:8181/access/v1/evaluation \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "agent", "id": "ai-assistant" },
    "resource": { "type": "mcp_tool", "name": "database__query" },
    "action": { "name": "invoke" }
  }'

{
  "allowed": true,
  "reason": "Access granted via role",
  "access_path": "role"
}

# Denied request — AI agent tries to drop a table
curl -s -X POST http://localhost:8181/access/v1/evaluation \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "agent", "id": "ai-assistant" },
    "resource": { "type": "mcp_tool", "name": "database__execute", "attributes": { "sql": "DROP TABLE users" } },
    "action": { "name": "invoke" }
  }'

{
  "allowed": false,
  "reason": "BLOCKED: DROP operations are not permitted for AI agents"
}

Configuration

The agent loads config from YAML (--config <path>, ./authzx-agent.yml, or ~/.authzx/agent.yaml). Environment variables override YAML values.

Env var	YAML key	Default	Description
AUTHZX_API_KEY	api_key	— (required for cloud mode)	API key from AuthzX Cloud
AUTHZX_CLOUD_URL	cloud_url	https://api.authzx.com	AuthzX Cloud base URL
AUTHZX_TENANT_ID	tenant_id	(auto-resolved)	Tenant ID; auto-detected from bundle if not set
AUTHZX_LISTEN_ADDR	listen_addr	0.0.0.0:8181	HTTP listen address
AUTHZX_POLL_INTERVAL	poll_interval	30s	How often to sync policies from the cloud
AUTHZX_CACHE_DIR	cache_dir	~/.authzx/bundles	Directory for persisted policy bundles
AUTHZX_LOG_LEVEL	log_level	info	Log verbosity (debug, info, warn, error)
AUTHZX_DECISION_LOG	decision_log	false	Enable structured JSON decision logging to stdout

Modes

Cloud mode (default)

The agent connects to AuthzX Cloud, pulls your tenant's policy bundle, and keeps it synced on the configured interval. This is the standard production deployment.

AUTHZX_API_KEY=your-key authzx-agent

Local mode

Load policies from a local .rego file instead of the cloud. No API key or cloud account required.

authzx-agent --policy ./examples/policy.rego

See examples/policy.rego for a starter policy.

Local mode is useful for:

• Self-hosted deployments without cloud dependency
• CI/CD pipeline testing
• Policy authoring and iteration

Health and Observability

Endpoints

Endpoint	Purpose
GET /healthz	Liveness check. Returns 200 while the process is running. Includes bundle revision, sync age, and degraded status.
GET /readyz	Readiness check. Returns 200 once a policy bundle is loaded (from cache or cloud). Returns 503 until ready.
GET /metrics	Prometheus metrics (decisions total, latency histogram, sync status, degraded state).

Decision logging

Enable structured decision logs for auditing and debugging:

AUTHZX_DECISION_LOG=true authzx-agent

Each /access/v1/evaluation call emits a JSON log line:

{
  "time": "2026-04-19T14:03:11.482Z",
  "level": "INFO",
  "msg": "decision",
  "subject_id": "user-123",
  "resource_id": "doc-456",
  "action": "view",
  "allowed": true,
  "reason": "Access granted via role",
  "access_path": "role",
  "ms": 0.42
}

Key metrics

Metric	Type	Description
authzx_agent_decisions_total	counter	Total authorization decisions (by allowed, access_path)
authzx_agent_decision_duration_seconds	histogram	Evaluation latency
authzx_agent_degraded	gauge	1 when serving from stale cache
authzx_agent_bundle_last_sync_timestamp_seconds	gauge	Unix timestamp of last successful sync

MCP Gateway

Using AI agents with MCP (Claude Code, Cursor, VS Code, GitHub Copilot)? The AuthzX MCP Gateway sits in front of your MCP servers and uses the AuthzX Agent to authorize every tool call before it executes.

Feedback

• GitHub Issues — Bug reports and feature requests
• Documentation — Guides and API reference

License

Apache-2.0 — see LICENSE.