Per-agent API keys

Why agent-scoped credentials

Today, an organisation usually has one shared API key per service that all its agents reuse. If one agent is compromised, the shared key has to be rotated and every agent re-issued. Forensic attribution ("which agent did this?") is impossible from logs alone.

Per-agent keys mirror Stripe's restricted-key model: each agent gets its own key, scoped to a specific Passport, individually rotateable, individually revocable. Every API call carries the key in Authorization: Bearer aii_agent_… and our verifier middleware can resolve the call back to the verified identity in one lookup.

Key shape

# Live key
aii_agent_live_<32-char base32>

# Test key (sandbox)
aii_agent_test_<32-char base32>

# In Authorization header
Authorization: Bearer aii_agent_live_K3R2N9MQXJZHB7VFTPYWGS46DCAEU8Y5

Keys are SHA-256-hashed at rest. The full key is shown exactly once at creation time and never stored in plaintext. Lost keys are rotated, not recovered.

Per-key constraints

• Identity binding — each key is bound to exactly one Passport (aii_) at creation. Cannot be re-bound.
• Scope — allow-list of action verbs the key may invoke. Default: empty (deny-all). Mirrors the intent declaration on the bound Passport.
• Rate limits — per-key requests-per-minute caps, independent of organisational tier limits.
• Spending caps — per-key max transaction value (USD), useful for agents calling payment APIs on behalf of users.
• Lifetime — keys expire automatically (default 90 days). Rotation is a single API call with configurable grace period for in-flight requests.
• Network restrictions — optional CIDR allow-list for keys used from fixed-IP infrastructure.

Verifier middleware

Servers that want identity-aware authorisation install our middleware. One line; key gets resolved to its Passport, scope checked, rate limited, audit log emitted:

import { aiIdentityKeyAuth } from "@aiidentity/sdk/server";

app.use(aiIdentityKeyAuth({
  required_tier: "creator_verified",
  required_score: 700,
  required_actions: ["read:account_summary"],
  on_violation: "deny" // or "warn"
}));

// Inside any handler
app.get("/account/:id", (req, res) => {
  // req.aii.identity is the resolved Passport record
  // req.aii.key is the scoped key
  // req.aii.score is the live Trust Score
  res.json({ /* ... */ });
});

Audit trail

Every authenticated call is logged with the key ID, the bound Passport, the action, the source IP, the result, and a content hash. The log is HMAC-chained for tamper-evidence (each entry includes the HMAC of the previous entry, so removing an entry breaks the chain).

Roadmap

Per-agent keys ship in v0.9 alongside the verifier middleware. Free-tier identities can generate one test key (rate-limited). Paid tiers get production keys with full rotation + audit features. Spending-cap enforcement and CIDR allow-lists ship in v0.9.1.

This spec deliberately stays compatible with the existing per-organisation API key model for backward compatibility — existing integrations don't need to change. Per-agent keys are an additional credential type, not a replacement.