Agent Identity Registry

The Agent Identity Registry provides a persistent identity layer for AI agents. Each registered agent receives a Decentralized Identifier (DID) bound to its organization, with rotatable key material and capability attestations. This is the foundation for agent-to-agent trust and enables cryptographic authentication in MCP tool calls and multi-agent workflows.

Overview

Unlike ephemeral session tokens, agent identities are persistent and organization-bound. An agent's capabilities are still ephemeral — task-scoped, time-bound, and issued dynamically through mandates — but the identity itself persists across sessions and mandate lifecycles.

Concept	Description
Agent DID	A persistent decentralized identifier in the format did:mandaitor:{tenant}:{agent_id}
Key Material	Ed25519 key pair for signing. Supports rotation with 30-day grace period for old keys
Mandate Binding	Agents can be bound to one or more mandates, establishing their authorized scope
Lifecycle	Agents follow the same lifecycle as mandates: ACTIVE → SUSPENDED → REVOKED

Registering an Agent

import { MandaitorClient } from "@mandaitor/sdk";

const client = new MandaitorClient({
  apiKey: process.env.MANDAITOR_API_KEY,
  tenantId: "tnt_your_tenant_id",
});

const agent = await client.post("/agents", {
  name: "validation-agent-v3",
  description: "Handles BIM validation for construction projects",
  capabilities: ["construction.validation.*", "construction.documentation.read"],
  metadata: {
    version: "3.1.0",
    framework: "langchain",
  },
});

console.log(agent.agent_id); // "agt_01HXYZ..."
console.log(agent.did);      // "did:mandaitor:tnt_abc:agt_01HXYZ..."

Resolving a DID Document

Each agent's DID resolves to a standard DID Document containing its public key material:

GET /agents/{id}/did
Content-Type: application/did+json

The response follows the W3C DID Core specification and includes verification methods that can be used by external systems to verify signatures produced by the agent.

Key Rotation

Agent keys should be rotated periodically. During rotation, the old key remains valid for 30 days to allow in-flight operations to complete:

const rotated = await client.post(`/agents/${agentId}/rotate`, {
  reason: "Scheduled quarterly rotation",
});
// "Key rotated successfully. Old key scheduled for deletion in 30 days."

Binding Agents to Mandates

An agent must be bound to at least one mandate before it can use the MCP Authorization Server. Binding establishes the link between the agent's identity and its authorized scope:

await client.post(`/agents/${agentId}/bind`, {
  mandate_id: "mdt_abc123",
});

A single agent can be bound to multiple mandates simultaneously. When verifying a tool call via MCP, the authorization server evaluates all bound mandates to determine whether the action is permitted. Bindings can also be removed without revoking the agent, which is useful when a project ends or a mandate is superseded.

Operation	Endpoint	Purpose
List agents	GET /agents	Returns registered agents for the tenant.
Get agent	GET /agents/{id}	Retrieves one agent including lifecycle status and binding metadata.
Bind mandate	POST /agents/{id}/bind	Adds a mandate binding to an agent identity.
Unbind mandate	DELETE /agents/{id}/bind/{mandateId}	Removes one mandate binding while keeping the agent active.

await client.delete(`/agents/${agentId}/bind/${mandateId}`);

Agent Lifecycle

Agents support the same lifecycle transitions as mandates:

Action	Endpoint	Effect
Suspend	POST /agents/{id}/suspend	Temporarily disables the agent. All MCP sessions are invalidated.
Reactivate	POST /agents/{id}/reactivate	Re-enables a suspended agent.
Revoke	POST /agents/{id}/revoke	Permanently disables the agent. Cannot be undone.

caution

Revoking an agent is permanent. All mandate bindings are removed and the agent's DID is marked as deactivated. This action cannot be reversed.