Permission Catalogs

Permission catalogs are immutable, cryptographically signed snapshots of what actions a gate permits, at what price, and with what SLA guarantees. They are the foundation of the agent commerce layer.

··

What is a permission catalog?

A permission catalog is a signed, versioned document that defines:

Which actions agents can perform through a gate
The pricing for each action (per_call, per_minute, subscription)
The SLA guarantees (uptime basis points, response time)
The trust requirements (L1/L2/L3 for each permission)
Any constraints that apply (rate limits, spend caps, approval thresholds)

When you publish a catalog, it becomes an immutable snapshot, it cannot be edited or deleted. Agents that receive a passport pinned to a specific catalog version are guaranteed those terms forever.

Key properties

Immutable

Published catalogs have database-level immutability triggers, they cannot be updated or deleted. Version history is preserved permanently.

Cryptographically signed

RFC 8785 canonicalization → SHA-256 content hash → Ed25519 (an industry-standard elliptic curve signing algorithm) signature by the gate's signing key. Agents can verify without trusting the server.

Trustless verification

Agents recompute the content hash and verify the Ed25519 signature locally. Discovery results include the signature, no trust required.

Breaking change detection

The system detects permission removals, price increases, SLA downgrades, and fee increases. Agents are notified before accepting new terms.

How catalogs connect to passports

When a passport is issued, it is pinned to the current catalog version via catalog_content_hash and catalog_version. These fields are immutable after issuance.

The gate verifies the catalog pin on every check. If a catalog is published with tampered content, existing passports will fail verification, preventing silent price manipulation.

If you need to update terms, you must:

Publish a new catalog version
Agent reviews the breaking change diff
Agent calls POST /api/passports/[id]/reissue to accept the new version
Old passport is revoked; new one is pinned to the new version

Full Guide

Building & Publishing Catalogs

Visual catalog builder, publish flow, version management.

Service Discovery

How agents find and verify catalog offerings.

Anti-Bait-and-Switch

Passport pinning and the reissue consent flow.

Billing & Metering

Consumption attestations and settlement.

Enforcement Layer, Catalog pricing constraints flow through the enforcement layer.
Attestations, Consumption attestations reference the catalog version.
Commerce API, Full catalog publishing and discovery API reference.

Anonymous Access Issuing Passports