APS · Agent Passport System
Developer Documentation

Build with the Agent Passport System

APS gives an AI agent a verifiable identity, ties it to the person or company it represents, scopes what it is allowed to do, and signs every action so the proof travels with the action instead of living in a log you check after something breaks.

This page gets you from install to a working governed action, then explains the core primitives and, plainly, what the receipts do and do not prove. Everything here is open source under Apache 2.0. The signed-bytes spec is CC0.

Install Quickstart Core concepts Receipts The gateway Compliance evidence Status labels Next steps

Install

The TypeScript SDK is the reference implementation. The 2.6 line is the stable release and carries the full feature set:

npm install agent-passport-system

There is a Python implementation on PyPI for verifier and signing work, and a Model Context Protocol server that exposes APS as tools to any MCP-capable agent:

# Python implementation
pip install agent-passport-system

# MCP server (governance as tools)
npm install -g agent-passport-system-mcp && npx agent-passport-system-mcp setup

A Go implementation is published for verifier and signing work in Go services. Go has no registry publish step; it is distributed by module path:

go get github.com/aeoess/agent-passport-go@v0.2.0-alpha.1

On the alpha tag. A plain npm install agent-passport-system resolves to the older stable line. Use @alpha to get the current 2.6 feature set. A stable 2.6 cut follows once the receipt-identity field is content-derived; until then the API is exercised by the full conformance suite and is safe to build on with a pinned version.

Quickstart

The curated entry point is agent-passport-system/core, which exposes the 24 functions that cover most integrations: identity, delegation, enforcement, commerce, reputation, and key management. The full root import stays available for everything else.

import {
  createPassport, createDelegation,
  evaluateIntent, commercePreflight, generateKeyPair
} from 'agent-passport-system/core'

The shape of a governed action is always the same four moves:

  1. Identity. Generate an Ed25519 keypair and create a passport for the agent. The passport ties the agent to the principal it represents and carries a grade from 0 to 3.
  2. Delegation. The principal issues a scoped delegation to the agent. Scope can only narrow as it is passed on, never widen.
  3. Enforcement. Before the agent acts, evaluateIntent checks the action against the delegation and policy. The agent signs the intent, the policy engine signs the evaluation, and the agent signs the execution receipt. The agent cannot skip the check.
  4. Receipt. The action produces a signed receipt that states the authority it ran under and what it proves.

For commerce, commercePreflight runs a five-gate check (valid passport, scope, spend limit, merchant allowlist, idempotency) with a human-approval threshold for high-value transactions. Full runnable examples live in the repository README and the test suite, which is the source of truth for exact call signatures on the version you installed.

Core concepts

The protocol rests on a single rule: authority can only decrease at each transfer point. A login authorizes a session. APS authorizes a specific action, at a specific time, under a specific policy, for a specific principal.

Identity Canonical

Ed25519 passports with grades 0 to 3, key rotation, and did:aps identifiers. APS also accepts did:key, did:web, SPIFFE SVIDs, and OAuth tokens, so an agent can carry the identity your stack already issues.

Delegation Canonical

Scoped authority with monotonic narrowing. Sub-delegation can only reduce scope, never add to it. Cascade revocation propagates through the full chain, so revoking a parent authority invalidates everything derived from it.

Enforcement Canonical

A three-signature action chain: the agent signs the intent, the policy engine signs the evaluation, the agent signs the execution receipt. Because the evaluation sits between intent and execution, the agent cannot act without being checked.

Commerce Production-Extension

A five-gate preflight for payments: valid passport, scope check, spend limit, merchant allowlist, and idempotency, with configurable human-approval thresholds above a value you set.

Reputation Production-Extension

Bayesian trust scoring across five tiers. Authority is earned per scope, not globally, and passport grades compound with behavioral history.

Receipts: what they prove, and what they do not

Every action produces a signed receipt, and receipts are graph-composable: each claim links to the authority, policy, action, observation, or evidence it depends on, so a verifier can walk from any receipt back to its supporting facts and stop at the boundary it cares about.

What a standard enforcement receipt proves: the gateway observed the agent issue this action under the cited delegation chain, and the signed body has not changed since signing. That is a real, checkable claim.

Read this before you build on receipts

A receipt states its own evidentiary weight, and you must honor it. A self_attested receipt, where the agent signed without independent attestation, carries less weight than a gateway_observed or runtime_attested one. The capture_mode and self_attested fields are part of the claim, not metadata. A verifier must reject self-attested evidence presented as observed evidence. A receipt proves authority and integrity of the recorded action. It does not prove the action was wise, that logging coverage was complete, or that the world matched the claim.

The gateway

The SDK gives you the primitives. The gateway is the enforcement boundary that runs them as a service: it is both judge and executor, evaluating each action against the delegation and policy before it happens and emitting the signed receipt. Gateway evaluation runs in single-digit milliseconds.

The protocol and SDK are open source. The hosted gateway is a separate product for teams that want enforcement, audit evidence, and tenant isolation without running the infrastructure themselves. If that is your situation, get in touch.

Compliance evidence

In regulated settings, including healthcare, auditors increasingly require evidence of who authorized an automated action, that the authority was scoped, that it was revocable, and that the record has not been tampered with. APS receipts supply exactly that class of evidence: a signed, tamper-evident record of the authority in effect for each action and the human or policy approvals that gated it.

What that evidence can support, in plain terms: a record of processing and access decisions, proof that a human-in-the-loop approval gated a given action, the scope and authority a decision ran under, and a tamper-evident monitoring trail. These map to the kinds of obligations frameworks such as the EU AI Act, GDPR, SOC 2, ISO 42001, and the NIST AI RMF increasingly require.

An honest boundary

APS supplies evidence for controls. It does not, by itself, make any organization compliant with any regulation, does not constitute a legal determination, and covers only the interactions the gateway sees. Absence of a receipt does not prove absence of an event. Treat APS as the evidence layer in a compliance program, not as the program.

Status labels

Every primitive carries one of three labels so you know how much weight it can bear today:

Next steps