# What is an agent identity? A definition and a reference design

*2026-10-02*

An agent identity is the handle, address, credentials and permissions that let software act as a distinct, accountable party. What it contains, why a shared API key is not one, and how to model it.

## Definition

An agent identity is a durable, addressable record that represents one autonomous software agent as a distinct party. It has a unique handle, one or more channels through which others can reach it (an email address, an A2A endpoint), its own credentials scoped to that agent alone, a lifecycle (active, suspended, reinstated), and an audit trail of what it did. It is separate from the human or organization that owns it, and separate from the model or framework that powers it.

## Why a shared API key is not an identity

Most agents today act through a credential that belongs to a person or a service: a developer's Gmail login, a team API key, a shared bot account. That works until you need to answer one of three questions. Which agent did this? Who is responsible for it? What was it allowed to do? A shared credential cannot answer any of them, because every agent that holds it looks the same to the outside world.

- Attribution: actions are recorded against the agent, not against whoever holds the key.
- Revocation: you can stop one agent without rotating a credential that ten other things depend on.
- Least privilege: a key bound to one identity cannot read another identity's mail or act as it.
- Reachability: other agents and people can address this agent directly, instead of going through its owner.

## The parts of an agent identity

- Handle: a short, globally unique name such as support-agent. It is the stable way to refer to the agent.
- Mailbox: a deliverable email address created at the same moment as the identity. An agent without an address is not much of an agent.
- Keys: API keys scoped to the identity. An organization key can manage identities; an agent key acts only as itself.
- Event log: an append-only record of what happened to and around the agent, which the agent can wait on.
- Permissions: who may reach it (allow and block rules, public or private) and what it may do.
- Lifecycle: it can be suspended with a stated reason, and reinstated, without deleting its history.
- Owner: a verified human or organization behind it, so other parties know someone is accountable.

## A minimal implementation

```ts
import { AgentClient } from "@agentidentity/sdk";

const admin = new AgentClient({ baseUrl: "https://api.agent-identity.dev", apiKey: process.env.AID_ORG_KEY! });

// Identity and mailbox are created together.
const agent = await admin.identities.create({ handle: "support-agent", displayName: "Support Agent" });
console.log(agent.mailboxAddress);

// A key that can only act as this agent.
const key = await admin.apiKeys.create({ name: "support-agent runtime", identityId: agent.id });

// Stop one agent without touching the others. Reversible, and the reason is recorded.
await admin.identities.suspend(agent.id, "Sending to unverified recipients");
```

## Identity versus authentication versus authorization

Authentication proves a caller holds a credential. Authorization decides what that credential may do. Identity is the layer that says which agent the credential stands for, so the other two have something stable to attach to and the audit log has someone to name. In Agent Identity, a key is bound to an identity at creation and the service rejects a key whose identity does not belong to the key's organization, so a key cannot be pointed at a stranger's agent.

## Frequently asked questions

Is an agent identity the same as an OAuth client? No. An OAuth client authorizes an application to act for a user. An agent identity is the agent as a party in its own right: it receives mail, is addressed by other agents, and has its own history.

Does every agent need its own email address? If it communicates with people or other services over email, yes: replies need somewhere to land, and threading, bounces and complaints have to be attributable to one agent.

Can an agent create its own identity? Yes. An agent can register an organization, name a human owner, and have that owner confirm with a 6-digit code. Until the owner confirms, the organization can only email its owner.

## Read more

- Identities: https://www.agent-identity.dev/docs/concepts/identities
- Authentication: https://www.agent-identity.dev/docs/getting-started/authentication
- Agent signup: https://www.agent-identity.dev/docs/getting-started/agent-signup

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