agentic-auth

Authorization for multi-hop AI agent systems. Before any call is dispatched, at every hop, one question gets answered: is this caller allowed to do this, right now?

Documentation

The problem

An agent that calls another agent that calls a tool is three authorization decisions, not one. Most stacks make the first and assume the rest. So when a prompt injection reaches the third hop, nothing is standing there — the agent is already holding a token that was scoped for the user's original request, and the tool has no way to know the request it is serving is not the one the user approved.

What this does

One worked example, which is also the walkthrough notebook:

The refusal is written down before the call would have gone out. An allowed call that cannot be recorded is refused, never dispatched unrecorded.

How it fits your architecture

   Agent ──► Enforcement point ──► PDP ──► decision + audit row
                   │                 │
                   │                 └── policy compiled from manifests
                   └── forwards only if allowed, with a narrowed hop token

• Manifests declare what each agent may do. A compiler turns them into a policy DAG.
• A PDP decides every hop and records every decision before anything is dispatched.
• Enforcement points sit where you need them. Pick one:

• Tokens narrow at every hop (RFC 8693 exchange), carrying an act chain that says who is acting for whom.
• Everything is auditable. The decision log is append-only, with every decision linked to its parent, and queryable by action, agent, or delegation chain.
• CI catches drift. agentic-auth drift check fails a pull request when an agent's observed calls include an edge its manifests never declared.

Install

Installs as authzai, imports as agentic_auth. Pick the part you need:

Add otel to any of these for OpenTelemetry traces and logs, or install all for everything. Code written against 0.1.x imported app.*; rename the imports with sed -E 's/\b(from|import) app\./\1 agentic_auth./g'.

Quickstart

Requires Docker and Python 3.12+.

git clone https://github.com/xinweiiiii/agentic-auth
cd agentic-auth

docker compose up -d                      # PostgreSQL + Redis
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev,otel]'
alembic upgrade head

uvicorn agentic_auth.main:app --port 8099  # the control plane

Check it is up:

curl -sS http://127.0.0.1:8099/readyz      # {"status":"ready"}

In a second shell, register the example agents and watch the guardrail refuse something:

export CP=http://127.0.0.1:8099
export AGENTIC_AUTH_ADMIN_TOKEN=dev-admin-token
export AUTH="Authorization: Bearer $AGENTIC_AUTH_ADMIN_TOKEN"

# 1. Register three agents that delegate to each other.
#    Their tools' capability sources are not running locally, so discovery is
#    unavailable — a recorded override reason reconciles them anyway.
agentic-auth manifest register-dir examples/drift-fixture/manifests \
  --control-plane $CP --override-reason "local quickstart"

# 2. See what the manifests compiled to. This is the policy, not the declaration.
curl -sS $CP/v1/scopes/bank-assistant/catalog -H "$AUTH"

# 3. A user consents to one scope. This pins a policy version for the session.
curl -sS -X POST $CP/v1/consent -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"scope":"bank-assistant","user_sub":"user:alice"}'

That returns a session_id and a root_grant. Use the grant to ask for a decision:

# 4. Ask to close an account — something nobody consented to.
curl -sS -X POST $CP/v1/authorize \
  -H "Authorization: Bearer <root_grant>" -H 'Content-Type: application/json' \
  -d '{"session_id":"<session_id>","caller":"bank-assistant",
       "target":"mcp://accounts.internal/terminate_account",
       "data_class":"account.write","guarantee":"full"}'

{ "outcome": "deny", "reason": "OUT_OF_SCOPE", "hop": 1, "policy_version": 1 }

Refused before the call leaves, and written down either way:

# 5. Every decision is recorded, queryable, and append-only.
curl -sS "$CP/v1/decisions?outcome=deny" -H "$AUTH"

To see the allow path, agents need their capability sources reachable and tokens exchanged per hop. The walkthrough notebook stands all of that up for you and asserts its own results:

pip install -e '.[notebook]'
cd examples/e2e-notebook && jupyter lab customer_walkthrough.ipynb

Next: Enroll your first agent is the 30-minute guided version. The end-to-end walkthrough is that notebook, rendered with its real output.

Configuration

Every option is read with an AGENTIC_AUTH_ prefix. Copy .env.example to .env and adjust — it documents each setting inline, including which ones are unsafe to leave empty outside development.

See CONFIGURATION.md for the organised reference.

Phases 4–6 are off by default. With every flag off, you get manifest-driven authorization, token exchange, and the audit chain — and nothing else changes.

Observability

Prometheus metrics at /metrics, with no identities in any label — not as a setting, by construction. OpenTelemetry traces and logs are opt-in and degrade to a no-op when the SDK is absent:

docker compose --profile observability up -d   # Collector + Jaeger + Prometheus

Shipped dashboards and alert rules are in observability/.

Documentation

Full documentation is at authzai.dev:

Normative wire formats a third party implements against live in docs/ — the canonicalization and binding hash and the verifier library contracts, plus the machine-readable schemas in docs/contracts/ that the test suite holds the code to.

Contributing

See CONTRIBUTING.md. Issues and pull requests are welcome.

To report a security vulnerability, do not open an issue — see SECURITY.md.

Licence

Apache-2.0. See LICENSE and NOTICE.