# A security model for agent identities: scoped keys, verified owners, signed webhooks

*2026-10-02*

The controls that keep autonomous agents accountable: keys bound to one identity, a verified human behind every organization, signed and replay-resistant webhooks, an audit log, and a kill switch.

## Threat model

The realistic risks with agents are not exotic. An agent is manipulated by a prompt injection into emailing a stranger. A leaked key lets someone act as the whole organization. A webhook endpoint is called by someone pretending to be the service. A misbehaving agent keeps running because stopping it means rotating a shared credential. Each control below answers one of these.

## 1. Keys are scoped to one identity

An organization key can manage identities and keys. An agent key acts only as the identity it was created for. At creation the service checks that the identity belongs to the key's organization, and the same check runs when the key is used, so a key cannot be pointed at another organization's agent. Keys are stored hashed and shown once.

## 2. A verified human behind every organization

Signup is open and needs no card, so the abuse control is verification: naming an owner emails them a 6-digit code that expires in 15 minutes and allows five wrong guesses. Until it is entered, the organization can only email that owner a few times a day and can only send A2A tasks inside the organization. An unverified organization cannot reach a stranger, which is what makes open signup safe.

## 3. Signed, replay-resistant webhooks

Each delivery carries x-aid-request-id, x-aid-timestamp and x-aid-signature. The signature is an HMAC-SHA256 over the request id, the timestamp and the raw body, sent as v1=<hex>. Verification compares in constant time and refuses a delivery older than five minutes, which blocks replays.

```ts
import { verifyWebhook, WebhookVerificationError } from "@agentidentity/sdk";

try {
  const { event } = await verifyWebhook({ secret: process.env.AID_WEBHOOK_SECRET!, body: rawBody, headers: req.headers });
  await handle(event);
} catch (e) {
  if (e instanceof WebhookVerificationError) return res.status(401).end();
  throw e;
}
```

Secrets rotate without downtime: client.webhooks.rotateSecret(id) issues a new secret and keeps the old one signing for 24 hours, so a header can carry two signatures while receivers switch.

## 4. An audit trail that names the actor

Changes that matter to security are recorded on the same event log, with the actor (the kind of key and its id) and never a secret: api_key.created, api_key.revoked, identity.created, identity.suspended, identity.reinstated, webhook.created, webhook.secret_rotated and organization.owner_verified, plus changes to who can reach an agent. GET /v1/events?types=api_key.* narrows to a family.

## 5. A kill switch that is reversible and explained

Suspending an identity stops it sending and receiving without deleting its history. A reason is required, because a suspension with no stated cause is useless to whoever reads the audit trail later. Reinstating lifts it. An agent cannot suspend or reinstate itself.

## 6. Access control between agents

Agents are private by default. A block rule beats everything. Cross-organization calls need both ends to agree, and refusals do not reveal the other side's private rules. See the A2A access post for the full decision order.

## Checklist for running agents in production

- Give every agent its own identity and key. Do not share an organization key with agents.
- Store the owner verification code flow in your onboarding, not in the agent's prompt.
- Verify every webhook against the raw body and reject on any WebhookVerificationError.
- Watch the audit log for api_key.created and identity.suspended.
- Have a documented reason string ready for suspensions.

## Read more

- Authentication: https://www.agent-identity.dev/docs/getting-started/authentication
- Webhooks: https://www.agent-identity.dev/docs/concepts/webhooks
- Events and audit log: https://www.agent-identity.dev/docs/concepts/events
- A2A access: https://www.agent-identity.dev/docs/a2a/trust

---
Docs: https://www.agent-identity.dev/docs · llms.txt: https://www.agent-identity.dev/llms.txt