Open Agent Identity

1. Introduction

Background

As AI agents become increasingly prevalent in consumer and enterprise applications, the need for a standardized identity and interaction protocol has become critical. Current approaches suffer from fragmentation: each agent platform implements proprietary discovery, authentication, and payment mechanisms, creating silos that limit interoperability.

Goals

OAI addresses these challenges by providing:

• Decentralized Identity — Agent identity rooted in DNS, requiring no central authority
• Verifiable Trust — Cryptographic verification of agent authenticity
• Capability Declaration — Upfront disclosure of agent permissions and pricing
• Secure Commerce — Payment flows where agents never access sensitive financial data
• User Privacy — Mechanisms to prevent cross-agent tracking
• Auditability — Cryptographic receipts for high-risk interactions

2. Terminology

3. Design Principles

DNS-Rooted Identity

Agent identity is anchored to domain names. An agent claiming to represent shoeco.example.com MUST be verifiable through DNS records controlled by that domain. This leverages existing trust infrastructure without requiring a new certificate authority or registry.

Transport Agnosticism

OAI defines message formats and flows, not transport mechanisms. Implementations MAY use WebSockets, HTTP/2, HTTP/3, WebRTC, or any reliable bidirectional channel.

Client-Enforced Security

Security policies are enforced by the client, not the agent. Agents declare their required capabilities; clients decide whether to grant them.

Privacy by Default

Users are identified to agents via pairwise identifiers that cannot be correlated across agents. Clients SHOULD NOT transmit unnecessary personal data.

Explicit Over Implicit

All agent capabilities, permissions, and costs MUST be declared explicitly in the manifest. Natural language in messages is for display purposes only; it MUST NOT be parsed for control flow.

4. Protocol Compatibility

Overview

OAI serves as the identity and discovery layer for the AI agent ecosystem. Once an agent is discovered and verified through OAI, clients can communicate using any supported protocol. OAI does not replace these protocols—it enables them by providing a universal identity foundation.

Supported Protocol Types

Manifest Protocol Declaration

Agents declare their supported protocols in the manifest:

{
  "protocols": {
    "oai": {
      "version": "1.0",
      "endpoint": "wss://ai.shoeco.example.com/v1/agent"
    },
    "mcp": {
      "version": "2024-11-05",
      "transport": "sse",
      "endpoint": "https://ai.shoeco.example.com/v1/mcp"
    },
    "a2a": {
      "version": "1.0",
      "endpoint": "https://ai.shoeco.example.com/v1/a2a"
    },
    "ucp": {
      "version": "1.0",
      "merchant_id": "shoeco_merchant_123"
    },
    "acp": {
      "version": "1.0",
      "stripe_account": "acct_1234567890"
    },
    "api": {
      "type": "rest",
      "endpoint": "https://ai.shoeco.example.com/v1/api",
      "documentation": "https://docs.shoeco.example.com/api"
    }
  }
}

Protocol Negotiation

When a client connects, it specifies which protocols it supports. The agent and client negotiate the best available protocol:

{
  "type": "session.init",
  "payload": {
    "client_id": "did:key:z6Mk...",
    "supported_protocols": ["oai", "mcp", "a2a"],
    "preferred_protocol": "mcp"
  }
}

What OAI Provides vs. Delegates

5. Client Authentication

Overview

OAI implements mutual authentication between clients and agents. Both parties have verifiable identities, and agents can choose which clients to accept or reject. This gives agents control over their ecosystem while maintaining openness.

Client Identity

Clients (applications that connect to agents on behalf of users) can also have OAI identities. A client's identity is established the same way as an agent's:

GET https://app.example.com/.well-known/agent-identity.json

{
  "oai_version": "1.0",
  "identity": {
    "name": "Example Assistant App",
    "handle": "@example-app",
    "domain": "app.example.com",
    "type": "client",
    "public_key": "MCowBQYDK2VwAyEA..."
  }
}

The type: "client" field distinguishes client applications from agents.

Mutual Authentication Flow

Session Init with Client Identity

{
  "type": "session.init",
  "id": "msg_001",
  "timestamp": "2026-02-02T15:30:00Z",
  "payload": {
    "client_id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "client_manifest": "https://app.example.com/.well-known/agent-identity.json",
    "client_domain": "app.example.com",
    "oai_version": "1.0",
    "granted_permissions": { ... }
  },
  "signature": "base64_signature_by_client_private_key..."
}

Agent Authorization Decision

Upon receiving a session.init, the agent:

1. Fetches the client manifest from client_manifest URL
2. Verifies the client via DNS (_oai-verify.{client_domain})
3. Verifies the signature using the client's public key
4. Checks the client against its authorization policy
5. Responds with session.ready or session.rejected

Authorization Policies

Agents can implement various authorization policies:

Session Rejection

{
  "type": "session.rejected",
  "id": "msg_001",
  "payload": {
    "reason": "client_not_authorized",
    "message": "This agent only accepts connections from verified partner applications.",
    "contact": "partnerships@shoeco.example.com"
  }
}

Session Key Exchange

After successful authentication, both parties exchange ephemeral session keys. This provides:

• Forward Secrecy — Compromise of long-term keys doesn't expose past sessions
• Replay Protection — Session-bound keys prevent message replay
• Session Isolation — Each session has unique encryption keys

Key Exchange Flow

// In session.init, client includes ephemeral public key
{
  "type": "session.init",
  "payload": {
    "client_id": "did:key:z6Mk...",
    "ephemeral_public_key": "MCowBQYDK2VwAyEA...",
    ...
  }
}

// In session.ready, agent includes its ephemeral public key
{
  "type": "session.ready",
  "payload": {
    "session_id": "sess_8x7k2m9p4n",
    "ephemeral_public_key": "MCowBQYDK2VwAyEA...",
    ...
  }
}

Both parties derive a shared session key using X25519 key agreement. All subsequent messages in the session are encrypted with this key.

Security Properties

6. Agent Discovery

Well-Known Endpoint

Agents are discovered via a standardized path on their host domain:

GET https://{domain}/.well-known/agent-identity.json

The response MUST be a JSON document conforming to the Agent Manifest schema.

Example Request

GET /.well-known/agent-identity.json HTTP/2
Host: support.shoeco.example.com
Accept: application/json
User-Agent: OAI-Client/1.0

Example Response

{
  "oai_version": "1.0",
  "identity": {
    "name": "ShoeCo Customer Support",
    "handle": "@shoeco-support",
    "domain": "shoeco.example.com",
    "description": "Official support agent for order tracking and returns.",

    // Worker Key (Hot) - used for signing in this deployment
    "public_key": "MCowBQYDK2VwAyEA_WORKER_KEY...",

    // Chain of Trust - proves Worker Key is authorized by domain owner
    "delegation": {
      "issuer_key": "MCowBQYDK2VwAyEA_MASTER_DNS_KEY...",  // Must match DNS TXT record
      "expiration": "2026-06-01T00:00:00Z",              // Limits damage if compromised
      "signature": "base64_master_signs_worker..."        // Master key signs worker key
    }
  },
  "endpoints": {
    "connect": "wss://ai.shoeco.example.com/v1/agent",
    "health": "https://ai.shoeco.example.com/v1/health"
  },
  "capabilities": { ... },
  "pricing": { ... }
}

Note: The delegation block is recommended for production. If omitted, public_key must match the DNS record directly. See Key Delegation.

Error Responses

7. Identity Verification

Overview

To prevent impersonation, agents MUST prove control of their claimed domain through DNS TXT records. This verification binds the agent's cryptographic identity to domain ownership.

DNS Record Format

Agent operators MUST publish a TXT record at:

_oai-verify.{domain}

The record value MUST follow this format:

v=oai1; id={agent_id}; key={public_key}; exp={expiration}

Example DNS Record

_oai-verify.shoeco.example.com. IN TXT "v=oai1; id=support_agent; key=MCowBQYDK2VwAyEA...; exp=2027-01-01T00:00:00Z"

Verification Process

1. Fetch the Agent Manifest from /.well-known/agent-identity.json
2. Extract the identity.domain and identity.public_key fields
3. Query DNS for _oai-verify.{domain} TXT records
4. Parse the TXT record value
5. If identity.delegation is present, follow the Key Delegation verification flow
6. Otherwise, compare the DNS key value to identity.public_key
7. If exp is present, verify it is in the future
8. Verification succeeds if keys match and expiration is valid

Key Delegation (Optional)

For enhanced security, agents MAY use key delegation to separate their long-term identity key from the operational key used for signing. This allows:

• Cold Storage — Master key stored offline in HSM or air-gapped system
• Key Rotation — Worker keys can rotate frequently without DNS changes
• Compromise Recovery — If worker key is compromised, rotate it; master key stays safe

Delegation Model

DNS Record (Master Key - Cold):
_oai-verify.shoeco.example.com TXT "v=oai1; key=MCowBQYDK2VwAyEA_MASTER_KEY..."
                                         │
                                         │ signs
                                         ▼
Manifest (Worker Key - Hot):
{
  "identity": {
    "public_key": "MCowBQYDK2VwAyEA_WORKER_KEY...",
    "delegation": {
      "issuer_key": "MCowBQYDK2VwAyEA_MASTER_KEY...",
      "expiration": "2026-02-02T18:00:00Z",
      "signature": "base64_master_signs_worker..."
    }
  }
}

Delegation Fields

Delegation Verification Process

When identity.delegation is present, clients MUST:

1. Verify delegation.issuer_key matches the DNS record's key
2. Verify delegation.expiration is in the future
3. Verify delegation.signature is a valid Ed25519 signature by issuer_key over the concatenation of public_key + expiration
4. If all checks pass, trust identity.public_key (the worker key) for this session

Verification Status

8. Agent Manifest

Identity Object

{
  "identity": {
    "name": "ShoeСo Customer Support",
    "handle": "@shoeco-support",
    "domain": "shoeco.example.com",
    "description": "Official support agent for order tracking, returns, and product information.",
    "public_key": "MCowBQYDK2VwAyEA_WORKER_KEY...",
    "delegation": {
      "issuer_key": "MCowBQYDK2VwAyEA_MASTER_DNS_KEY...",
      "expiration": "2026-02-02T18:00:00Z",
      "signature": "base64_master_signs_worker..."
    },
    "logo_url": "https://shoeco.example.com/assets/agent-logo.png",
    "operator": {
      "name": "ShoeСo, Inc.",
      "contact": "support@shoeco.example.com",
      "privacy_policy": "https://shoeco.example.com/privacy",
      "terms_of_service": "https://shoeco.example.com/terms"
    }
  }
}

The delegation field is optional. When present, the public_key is a worker key signed by the master key in DNS. See Key Delegation for details.

Identity Fields

* Required if delegation is present.

Endpoints with MCP Support

{
  "endpoints": {
    "connect": "wss://ai.shoeco.example.com/v1/agent",
    "health": "https://ai.shoeco.example.com/v1/health",
    "mcp": {
      "transport": "sse",
      "url": "https://ai.shoeco.example.com/v1/mcp"
    }
  }
}

The optional mcp endpoint enables Model Context Protocol integration for richer tool interactions.

9. Capabilities and Permissions

Overview

Agents MUST declare all capabilities they require. Clients MUST block any action not explicitly listed in the manifest. This creates a sandbox model where agents operate within declared boundaries.

Tools

{
  "capabilities": {
    "tools": [
      {
        "name": "order_lookup",
        "description": "Look up order status by order ID or email",
        "parameters": {
          "order_id": "string",
          "email": "string"
        }
      },
      {
        "name": "initiate_return",
        "description": "Start a return process for an order",
        "requires_confirmation": true
      }
    ]
  }
}

Permissions

{
  "capabilities": {
    "permissions": {
      "user_data": {
        "fields": ["email", "shipping_address"],
        "purpose": "Order lookup and delivery updates",
        "retention": "session"
      },
      "location": {
        "precision": "coarse",
        "purpose": "Find nearby stores"
      },
      "payments": {
        "enabled": true,
        "provider": "stripe",
        "max_amount": 100000
      }
    }
  }
}

Permission Types

MCP Compatibility

Agents MAY declare compatibility with the Model Context Protocol (MCP) to provide richer tool schemas:

{
  "capabilities": {
    "mcp": {
      "compatible": true,
      "version": "2024-11-05",
      "features": ["tools", "resources", "prompts"]
    },
    "tools": [
      {
        "name": "order_lookup",
        "description": "Look up order status",
        "mcp_schema": true,
        "inputSchema": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          }
        }
      }
    ]
  }
}

When mcp_schema: true, clients use the rich inputSchema for validation and UI generation. See Appendix C for full MCP integration details.

10. Session Management

Session Lifecycle

Session Initialization

{
  "type": "session.init",
  "id": "msg_001",
  "payload": {
    "client_id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "oai_version": "1.0",
    "granted_permissions": {
      "user_data": ["email"],
      "payments": true
    }
  }
}

Session Ready Response

{
  "type": "session.ready",
  "id": "msg_001",
  "payload": {
    "session_id": "sess_8x7k2m9p4n",
    "expires_at": "2026-02-02T20:30:00Z",
    "agent_greeting": "Hello! I'm the ShoeСo support agent. How can I help you today?"
  }
}

11. Interaction Protocol

Message Format

All messages follow a common envelope structure:

{
  "type": "{category}.{action}",
  "id": "{unique_message_id}",
  "timestamp": "{ISO8601_timestamp}",
  "session_id": "{session_id}",
  "payload": { ... },
  "signature": "{base64_signature}"
}

Message Categories

Rich UI Rendering

{
  "type": "ui.render",
  "payload": {
    "template": "product_card",
    "data": {
      "title": "6-Inch Premium Waterproof Boot",
      "price": { "amount": 19800, "currency": "USD" },
      "image_url": "https://shoeco.example.com/imgs/boot.jpg",
      "actions": [
        { "label": "Add to Cart", "action": "commerce.add_to_cart" }
      ]
    }
  }
}

12. Commerce and Payments

Zero-Touch Payment Model

OAI enforces a strict separation between payment requests and payment execution:

1. Agents request payment by sending a payment intent
2. Clients execute payment using stored credentials
3. Agents never access credit card numbers, bank accounts, or other sensitive financial data

Payment Request

{
  "type": "commerce.request_payment",
  "id": "msg_201",
  "payload": {
    "payment_id": "pay_req_88291",
    "provider": "stripe",
    "intent_secret": "pi_3MtwBwLkdIwHu7ix28aL_secret_...",
    "amount": { "value": 19800, "currency": "USD" },
    "description": "ShoeСo Premium Boot (Size 10)"
  },
  "security": {
    "confirmation_type": "standard"
  }
}

Confirmation Types

Supported Payment Providers

13. Pricing and Metering

Pricing Models

Free

{ "pricing": { "model": "free" } }

Flat Rate (Per Session)

{
  "pricing": {
    "model": "flat",
    "amount": 100,
    "currency": "USD"
  }
}

Metered (Per Turn)

{
  "pricing": {
    "model": "metered",
    "unit": "turn",
    "rate": 5,
    "currency": "USD",
    "description": "$0.05 per message"
  }
}

14. User Privacy

Pairwise Decentralized Identifiers

To prevent cross-agent tracking, clients MUST generate a unique Decentralized Identifier (DID) for each agent relationship:

User → ShoeСo Agent: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
User → Delta Agent:      did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH

ShoeСo and Delta receive different identifiers; they cannot correlate to build a unified user profile.

Data Minimization

Clients MUST implement data minimization:

• Only transmit data fields explicitly granted in permissions
• Strip unnecessary metadata from messages
• Do not transmit device identifiers, IP addresses, or hardware info unless required and permitted

Context Passports (State Management)

OAI replaces traditional "Login/Password" credentials with Client-Managed State. The user's relationship with an agent is defined by the Pairwise DID presented during the handshake.

• Guest Mode (Ephemeral): To interact anonymously, the Client generates a fresh, random DID. The Agent perceives this as a new user with no history.
• Return Mode (Persistent): To resume a relationship (e.g., accessing order history), the Client persists the DID associated with the Agent's domain. Upon reconnection, the Client re-presents the same DID, allowing the Agent to restore context.

User Sovereignty

The choice to persist or delete this identity lies entirely with the User (via the Client UI), effectively granting a "Right to be Forgotten" at the protocol level. No coordination with the Agent is required — deleting the DID from the local device severs the cryptographic link permanently.

Implementation Requirements

Device loss in Return mode means loss of Agent relationships. Clients SHOULD warn users and provide backup/export options.

15. Audit and Receipts

Overview

Every high-risk interaction MUST generate a cryptographic receipt signed by both the agent and client. This creates a non-repudiable audit trail stored on the user's device.

Receipt Format

{
  "receipt_id": "rcpt_xyz789",
  "timestamp": "2026-02-02T15:35:30Z",
  "session_id": "sess_8x7k2m9p4n",
  "action": {
    "type": "commerce.payment_confirmed",
    "message_id": "msg_201"
  },
  "payload_hash": "sha256:a3b8c9d2e4f5...",
  "signatures": {
    "agent": "base64_agent_signature...",
    "client": "base64_client_signature..."
  }
}

16. Error Handling

Error Codes

17. Security Considerations

Transport Security

• All connections MUST use TLS 1.3 or later
• Clients MUST validate server certificates
• Certificate pinning is RECOMMENDED for known agents

Message Authentication

• All messages from agents SHOULD be signed
• High-risk messages MUST be signed
• Clients MUST verify signatures before acting on high-risk messages

Replay Prevention

Messages MUST include unique message ID, timestamp within acceptable skew (5 minutes), and session ID. Clients MUST reject duplicate message IDs and messages with timestamps outside acceptable skew.

Injection Prevention

The protocol explicitly separates control and display. Natural language content is for display only; clients MUST NOT parse natural language for commands. All control flow uses structured type fields.

DNSSEC Enforcement

To prevent DNS spoofing attacks (e.g., "Coffee Shop" Man-in-the-Middle), OAI Clients MUST enforce DNSSEC validation when resolving the _oai-verify TXT record.

The Client MUST NOT trust the DNS response unless the chain of trust can be cryptographically verified back to the Root Trust Anchor. Clients MAY achieve this via:

• Local Validation: Requesting DNSSEC resource records (RRSIG, DNSKEY) and verifying them on the device
• Trusted Transport: Using a secure transport (DoH/DoT) to a recursive resolver that explicitly sets the Authenticated Data (AD) flag

Failure Modes

Capability Restrictions for Unverified Agents

When DNSSEC validation cannot be performed (domain lacks DNSSEC), the Client MUST treat the Agent as Unverified and block high-risk capabilities:

• payments — All payment requests MUST be rejected
• personal_data — Personal data transmission MUST be blocked
• tool_execution — Tools with risk_level: "high" MUST require additional user confirmation

Clients SHOULD display a visual indicator when interacting with Unverified agents to inform users of the reduced trust level.

Appendix A: JSON Schemas

Full JSON Schema definitions are available at:

• Agent Manifest Schema
• Message Envelope Schema

Appendix B: Example Flows

Complete Session Flow

Payment Flow

Appendix C: MCP Integration

Overview

The Model Context Protocol (MCP) is an open protocol for connecting AI models to external data sources and tools. OAI and MCP are complementary:

OAI provides the identity, commerce, and privacy layer. MCP provides the tool interaction layer. Together, they offer a complete solution.

Integration Architecture

Complete OAI+MCP Flow

MCP Tool Invocation Example

{
  "type": "mcp.tools_call",
  "id": "msg_mcp_003",
  "session_id": "sess_8x7k2m9p4n",
  "payload": {
    "name": "order_lookup",
    "arguments": {
      "order_id": "TL-98234"
    }
  }
}

Security Rules for MCP Integration

• Capability Enforcement: MCP tools MUST be declared in OAI manifest. Clients block undeclared tools.
• Permission Checks: MCP tools accessing user data require OAI permission grants.
• Payment Handling: MCP tools cannot process payments directly—use OAI commerce flows.
• Audit Trail: High-risk MCP operations generate OAI receipts.
• Prompt Injection: MCP prompts are for display only—clients MUST NOT execute embedded instructions.

Authors & Acknowledgments

Original Authors

The Open Agent Identity specification was created by:

• Basil Varghese, Autonomy Next, Inc.
• Sona Mathew, Autonomy Next, Inc.

Contributing Organizations

We welcome contributions from the community. Organizations and individuals who contribute to the specification will be acknowledged here.

Contact

For questions, feedback, or to contribute to the specification:

• Email: spec@openagentidentity.org
• GitHub: github.com/openagentidentity/spec

Version History

License

This specification is released under the Creative Commons Attribution 4.0 International License (CC BY 4.0). You are free to share and adapt this specification, provided you give appropriate credit to Autonomy Next, Inc. as the original creator.

Open Agent Identity is an open standard. Contributions and feedback are welcome.