What is AgentWrit?

AgentWrit gives AI agents temporary, task-scoped credentials instead of long-lived API keys.

When an AI agent needs to do something — read a customer record, call a vendor API, run a query — it asks the AgentWrit broker for a token. The token works for that specific task, expires in minutes, and can be yanked at four different levels the moment anything feels wrong. The agent never touches your long-lived credentials at all.

Think of it as an issuer of legal writs for software: narrow authority, time-limited, revocable at the source.

Why this matters

Traditional IAM was built for humans and long-running services — not for AI agents that spin up, do one task, and disappear. Agents are ephemeral, task-scoped, and delegate to other agents. They need credentials that match that lifecycle. AgentWrit was purpose-built for it.

What the audit trail covers: The broker logs credential lifecycle events — issue, renew, revoke, delegate, release, auth failures, and scope violations. It does not see what the agent does with the token at the resource server.

Want the full security model? → Concepts & threat model

Quick Start

Prerequisites: Docker. Five minutes to your first agent token.

# 1. Set a strong admin secret (broker exits without it)
export AA_ADMIN_SECRET="$(openssl rand -base64 32)"

# 2. Start the broker
docker run -d --name agentwrit \
  -p 8080:8080 \
  -e AA_ADMIN_SECRET \
  -e AA_BIND_ADDRESS=0.0.0.0 \
  -e AA_DB_PATH=/data/data.db \
  -e AA_SIGNING_KEY_PATH=/data/signing.key \
  -v agentwrit-data:/data \
  devonartis/agentwrit:latest

# 3. Confirm it's up
curl -s http://localhost:8080/v1/health | jq .

# 4. Authenticate as admin
ADMIN_TOKEN=$(curl -s -X POST http://localhost:8080/v1/admin/auth \
  -H "Content-Type: application/json" \
  -d "{\"secret\":\"$AA_ADMIN_SECRET\"}" | jq -r '.access_token')

# 5. Create a launch token (one-time agent registration credential)
LAUNCH_TOKEN=$(curl -s -X POST http://localhost:8080/v1/admin/launch-tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "demo-agent",
    "orch_id": "quickstart",
    "allowed_scope": ["read:data:*"],
    "ttl_seconds": 300
  }' | jq -r '.launch_token')

echo "Launch token: ${LAUNCH_TOKEN:0:20}..."

You now have a launch token. The agent presents this once to register and get its own scoped JWT.

Next steps from here:

How it works

AgentWrit implements the Ephemeral Agent Credentialing v1.3 security pattern — an 8-component architecture purpose-built for autonomous AI agents. The pattern was developed as part of the AI Security Blueprints project and AgentWrit is its reference implementation.

Detailed diagrams: Token Lifecycle · Security Topology

1. Operator creates a launch token with an allowed scope ceiling
2. App hands the launch token to the agent for a specific task
3. Agent registers with the broker (Ed25519 challenge-response), gets a short-lived JWT
4. Agent uses the JWT as a Bearer token against resource servers
5. Agent releases the token when done — or the broker revokes it at any of 4 levels

10 components, one binary. The broker handles identity, tokens, scopes, revocation, delegation, audit, app management, admin auth, observability, and persistence — all in a single Go binary with 5 direct dependencies.

Deep dive: Architecture diagrams & data flows →

See it in action — MedAssist AI Demo

The Python SDK includes MedAssist AI: a FastAPI web app where a local LLM dynamically creates broker agents with per-patient scoped credentials. You see scope enforcement, cross-patient denial, delegation, and audit — all in a real-time trace.

Run it: MedAssist AI demo → · Beginner's guide → · Presenter's guide →

SDKs

from agentauth import AgentAuthApp

# The SDK hides the Ed25519 challenge-response flow
agent = AgentAuthApp(broker_url="http://localhost:8080").register(
    launch_token=LAUNCH_TOKEN,
    task_id="read-customer-42",
    requested_scope=["read:data:customers:42"],
)

# Use the token at your resource server
response = httpx.get(url, headers=agent.bearer_header)

# Done — release the credential
agent.release()

Full SDK docs: Python SDK →

API at a glance

19 endpoints. Full schemas and examples in the API Reference →.

All errors return RFC 7807 application/problem+json.

Other install options

Docker Compose (clone + build locally)

git clone https://github.com/devonartis/agentwrit.git && cd agentwrit
export AA_ADMIN_SECRET="$(openssl rand -base64 32)"
./scripts/stack_up.sh
curl -s http://localhost:8080/v1/health | jq .

Tear down: ./scripts/stack_down.sh

Build from source (Go 1.24+)

go build -o bin/broker ./cmd/broker/
go build -o bin/awrit  ./cmd/awrit/
./bin/awrit init --config-path /tmp/agentwrit/config
AA_CONFIG_PATH=/tmp/agentwrit/config ./bin/broker

Pre-built Docker image tags

Verify the image (optional, recommended):

cosign verify devonartis/agentwrit:latest \
  --certificate-identity-regexp='^https://github.com/devonartis/agentwrit/\.github/workflows/release\.yml@' \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

Configuration

All env vars use the AA_ prefix. Only AA_ADMIN_SECRET is required — the broker exits without it.

Full config reference (all env vars, TLS/mTLS setup, config files, operator CLI): Operator guide →

Operator CLI (awrit)

go build -o bin/awrit ./cmd/awrit/
export AACTL_BROKER_URL=http://localhost:8080
export AACTL_ADMIN_SECRET="your-secret"

awrit init                                         # Generate broker config
awrit app register --name my-pipeline --scopes "read:data:*"  # Register an app
awrit revoke --level agent --target <agent-id>     # Revoke all agent tokens
awrit audit events --outcome denied --limit 20     # Query audit trail

Full CLI reference: awrit commands & flags →

Running tests

go test ./...              # All tests
go test ./... -short       # Unit tests only
./scripts/gates.sh task    # Build + lint + unit + security scan
./scripts/gates.sh module  # Full gates including Docker E2E

Documentation

License

AgentWrit is licensed under the PolyForm Internal Use License 1.0.0 — a source-available license designed for internal business use.

Free for internal use by anyone, including for-profit companies. Any individual, business, or organization may use and modify AgentWrit for their own internal operations at no cost and without contacting the licensor. This includes modification by contractors acting on behalf of a permitted user. Internal business use by a for-profit company is explicitly permitted and free.

Requires a commercial license:

• Hosted or managed-service offerings (SaaS) to third parties — paid or free
• Embedding AgentWrit in a product you sell or sublicense
• Resale or redistribution of AgentWrit or modified versions
• Any third-party access to a running AgentWrit instance, including shared installs across unrelated organizations

Dual-license contact: Non-commercial and research use (nonprofits, education, mentorship programs, open-source projects, trade groups) is typically free on request. Commercial embedding, resale, and hosted-service offerings require a paid commercial license. Email licensing@agentwrit.com with your use case.

See LICENSE for the full license text.

Built With

Built with help from Claude by Anthropic.