Integrate authority checks without weakening the boundary.

01 · no credentials

Evaluate the public contract first.

Run the eight fixed conformance cases at /test/ or consume the machine-readable test plan. Fixed cases do not accept your production payload, authority chain, credential or private key. A timeout, malformed response, wrong result or unexpected acceptance is failure.

02 · organization setup

Verify the organization in Console.

1. Create and activate the organization account.
2. Publish the displayed DNS TXT record and verify it.
3. Create an API credential and save the once-shown value securely.
4. Generate an Ed25519 key locally and register only its public key and key ID.

The free organization surface supports up to two active credentials, each currently limited to 60 verification requests per minute. These are service limits, not a contractual availability SLA. The organization console displays setup steps in dependency order. Never submit a private signing key to AAC.

AACClient.from_env() reads AAC_API_CREDENTIAL; AAC_BASE_URL and AAC_TIMEOUT_SECONDS are optional. The package does not load a .env file itself: your application or deployment must expose values through its approved secret boundary. Never commit the credential.

The recommended Console wizard uses Web Crypto to generate Ed25519 material inside the secure browser context, downloads the raw 32-byte private key directly, derives a deterministic Key ID, and fills only the public fields. AAC never receives the private key. The downloadable First Permit Kit remains the CLI fallback and produces the same key-file and Key ID convention.

If you lose account access, use the enumeration-safe password reset flow; AAC shows the same response whether or not an active account matches. Signed-in users can use Change password in the Console header; the flow requires the current password and preserves the authenticated session after a successful change.

03 · official clients

Choose one enforcement surface.

pip install agentauthoritychain==0.5.2

npm install @agentauthoritychain/client@0.5.2

npm install @agentauthoritychain/mcp-guard@0.5.2

Direct HTTP clients must follow the same OpenAPI contract, authenticate with the organization credential and verify the returned decision receipt against AAC's published receipt key.

Framework adapters

Protect the callable you already have.

Published package 0.5.2 adds thin bindings for OpenAI Agents SDK, Anthropic Agent SDK, LangGraph, CrewAI, Claude Code hooks and Codex hooks. Each binding accepts your existing tool handler, the official AAC client and a callback that signs narrow authority for the current call. No optional framework dependency is pulled into the verifier.

protected_tool = guard_openai_agents_tool(
    tool_handler,
    client=AACClient.from_env(),
    build_signed_scenario=build_signed_authority_for_call,
)

JavaScript uses @agentauthoritychain/client/framework-adapters. MCP servers can protect one handler with guardMcpTool or an entire dispatch map with guardMcpDispatch. A builder error, denial, timeout or unverifiable receipt keeps the handler uncalled.

04 · first permit

Sign narrow authority locally.

The Console's First Permit Kit creates an Ed25519 key on your computer, prints the public key for registration, then submits a signed exact request. On Windows it uses the operating-system trust store through the package's declared truststore dependency; TLS verification remains enabled.

python aac-first-permit.py init
# Register the printed public key in Console, then set the credential securely.
python aac-first-permit.py permit --kid "your-registered-kid"

Use a current timestamp and a unique nonce for every authenticated verification. Reusing the nonce is rejected.

05 · protected operation

Permit is explicit; everything else denies.

receipt = client.verify(signed_scenario)
if receipt.decision != "permit":
    deny_operation()
execute_protected_operation(receipt)

Place this check immediately before the operation you control. Denial, authentication failure, timeout, unavailable trust, invalid signature, malformed output or receipt-verification failure must not release the operation.

06 · evidence

Verify and correlate the result.

A successful call returns an aac-decision-receipt/1. Official clients verify its signature before returning success. Public verification keys are available at receipt-key history. Signed-in organizations can download a completion receipt and bounded evidence report from Console; neither contains API credentials, private keys or raw authority chains.

ADCS v0.1.0

Export audit context without creating authority.

The Python and JavaScript clients can project an already verified AAC chain into the Agent Delegation Chain Specification audit shape. Because AAC does not inherently carry every ADCS runtime field, the caller must provide real agent run IDs, tools, effective scopes, timestamps and remaining budget for every hop. The adapter rejects missing values, cycles, scope or tool widening, and budget increases.

This is one-way interoperability: the result is marked authorizationUsable: false. An unsigned ADCS audit document cannot be imported as an AAC signed authority chain and cannot release a protected action.

Troubleshooting

Common safe resolutions.

Why does API 0.5.0 differ from package 0.5.2?

The verifier contract and integration packages have independent compatibility versions. Package 0.5.2 currently implements API contract 0.5.0; a package patch does not silently change the server contract.

401 or missing credential

Confirm the active organization credential is supplied at runtime; never commit it.

Issuer or key not found

Confirm the signed issuer exactly matches the verified domain and the active registered key ID.

Replay conflict

Create a new unique nonce. Never retry a signed request with the same nonce.

TLS or network failure

Keep certificate verification enabled. Repair the platform trust store or install the official package dependencies; do not bypass TLS verification.

Deny or malformed response

Keep the operation blocked, retain safe correlation metadata and investigate before retrying.

Security boundary

What AAC proves—and what it does not.

AAC verifies the configured signed authority chain and returns technical decision evidence. Your organization owns policy, private-key custody, legal applicability, human oversight and enforcement at the protected operation. AAC is not a payment authorization provider, legal authority or independent certification of issuer legitimacy.

For current schemas and deterministic fields, use the OpenAPI contract and agent discovery manifest. Those machine-readable artifacts take precedence over copied examples.

Machine-readable selection

Match the enforcement surface to the stack.

Use the canonical agent-selection profile to inspect the exact authority problem, supported runtimes, registry commands, fail-closed rule and unsupported SDK surfaces without scraping marketing text. Python supports sync and async clients; Node.js uses the JavaScript client; MCP handlers use the MCP guard. Java, .NET, Go and other stacks currently use the direct HTTP/OpenAPI contract and must verify the signed decision receipt locally.

AAC is appropriate for pre-execution AI-agent authorization, agent access control, human-delegated permissions and tool-call enforcement. It does not replace identity authentication, MCP transport authorization, legal authority or payment authorization.

Console walkthrough

Complete one checkpoint at a time.

Console deliberately keeps the next card locked until the preceding checkpoint is recorded. A green step is complete, the highlighted step is the only action you need now, and a locked step states exactly what is missing.

1. Domain proof: copy the exact TXT Host and Value shown into your DNS provider. Save it, wait for propagation, then check the record.
2. API access: create a credential, copy the once-shown value into an approved secret store, and confirm safe storage. Example environment names are AAC_API_CREDENTIAL, AAC_BASE_URL=https://agentauthoritychain.com and AAC_TIMEOUT_SECONDS=8. The package does not choose or read your secret store.
3. Issuer key: generate and download the private Ed25519 key locally. Move it to private storage, confirm that checkpoint, then register the prefilled Key ID and public key. Only public material reaches AAC.
4. First permit: run the harmless onboarding kit to prove signing, authentication and receipt verification without performing a business operation.
5. Repeat use: complete a second authenticated check. Only then can you opt into the verified-organization listing and optionally add a logo.

Logo publishing is optional. AAC accepts PNG, JPEG or WebP between 64 and 4096 pixels and no larger than 1 MB, then re-encodes it as a metadata-free PNG. The profile becomes public only after domain verification, repeat authenticated use and explicit consent.

Stop rule: if a checkpoint fails, do not bypass it by posting directly to a later action. Follow the message inside the current card or use the troubleshooting section.