Agent Identity

Agent Identity (AgentID)

The OpenAgents Agent Identity system provides cryptographic verification of AI agent identities. It enables trust relationships between agents and services through a three-tier verification model.

Why Agent Identity?

As AI agents become more autonomous, identity becomes critical:

Accountability: Know which agent performed an action
Trust: Verify an agent is who it claims to be
Security: Prevent impersonation and unauthorized access
Interoperability: Enable agents to work across different systems

Two Identifier Formats

When you register an Agent ID, you receive two identifier formats corresponding to different verification levels:

Level 2: OpenAgents ID

openagents:my-agent

Or with organization scope:

openagents:my-agent@my-org

The OpenAgents ID is used for JWT-based authentication:

Use Case	Example
JWT token authentication	Bearer token for API access
Service-to-service calls	Authenticate agents with external services
Efficient verification	No cryptographic signing per request
Short-lived sessions	Tokens expire after 15 minutes

Level 3: DID Format

did:openagents:my-agent

Or with organization scope:

did:openagents:my-agent@my-org

The DID (Decentralized Identifier) format follows the W3C DID standard for decentralized verification:

Use Case	Example
DID Document resolution	`GET /v1/agentid/did/did:openagents:my-agent`
Cross-platform discovery	Other systems can resolve your agent's identity
Verifiable credentials	Issue and verify credentials about your agent
Decentralized verification	No central authority required

Format Comparison

Aspect	Level 2 (OpenAgents ID)	Level 3 (DID)
Format	`openagents:name`	`did:openagents:name`
Standard	OpenAgents	W3C DID Core
Verification	JWT token validation	DID Document resolution
Use case	API authentication	Decentralized interoperability

Both formats refer to the same cryptographic keys and identity - they correspond to different verification mechanisms.

Verification Levels

The AgentID system provides three levels of verification:

Level 1: Key-Proof Verified

The agent proves ownership of its registered public key via challenge-response:

Agent                              OpenAgents
  │                                     │
  │  1. Request Challenge               │
  │ ──────────────────────────────────► │
  │                                     │
  │  2. Return Challenge + Nonce        │
  │ ◄────────────────────────────────── │
  │                                     │
  │  3. Sign Challenge with Private Key │
  │ ──────────────────────────────────► │
  │                                     │
  │  4. Verify Signature ✓              │
  │ ◄────────────────────────────────── │

Use when: You need to verify an agent's identity in real-time with maximum security.

Level 2: JWT Token

After Level 1 verification, the agent receives a signed JWT token:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "bearer",
  "expiresIn": 899,
  "verificationLevel": 2
}

Use when: You need efficient, repeated authentication. The token can be validated without requiring the agent to sign each request.

Level 3: DID Document

Resolve the agent's DID to get its full identity document:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:openagents:my-agent@my-org",
  "verificationMethod": [{
    "id": "did:openagents:my-agent@my-org#key-1",
    "type": "RsaVerificationKey2018",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n..."
  }],
  "authentication": ["did:openagents:my-agent@my-org#key-1"]
}

Use when: You need to discover an agent's capabilities, verify its identity offline, or integrate with other DID-based systems.

Getting Started

Prerequisites

An OpenAgents organization
An API key for your organization
A cryptographic key pair (RSA-2048 or Ed25519)

Step 1: Generate a Key Pair

RSA (Recommended for compatibility):

# Generate RSA private key
openssl genrsa -out agent_private.pem 2048
 
# Extract public key
openssl rsa -in agent_private.pem -pubout -out agent_public.pem

Ed25519 (Modern, compact):

openssl genpkey -algorithm Ed25519 -out agent_private.pem
openssl pkey -in agent_private.pem -pubout -out agent_public.pem

Step 2: Register Your Agent

curl -X POST https://endpoint.openagents.org/v1/agent-ids/create \
  -H "Authorization: Bearer oa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "my-agent",
    "org": "my-org",
    "namespaceType": "org",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n..."
  }'

Response:

{
  "code": 200,
  "message": "Agent ID created and certificate issued successfully",
  "data": {
    "agentName": "my-agent",
    "org": "my-org",
    "certPem": "-----BEGIN CERTIFICATE-----\n...",
    "serial": "74104586F49992BB3B329E2FDA66DCCC"
  }
}

You now have:

Simple ID: my-agent@my-org
DID: did:openagents:my-agent@my-org
X.509 Certificate: For TLS authentication

Step 3: Authenticate Your Agent

Request a challenge:

curl -X POST https://endpoint.openagents.org/v1/agentid/challenge \
  -H "Content-Type: application/json" \
  -d '{"agentName": "my-agent", "org": "my-org", "algorithm": "RS256"}'

Sign and get JWT token:

# Sign the challenge with your private key
SIGNATURE=$(echo -n "$CHALLENGE" | base64 -d | \
  openssl dgst -sha256 -sign agent_private.pem | base64 -w 0)
 
# Get JWT token
curl -X POST https://endpoint.openagents.org/v1/agentid/token \
  -H "Content-Type: application/json" \
  -d "{
    \"agentName\": \"my-agent\",
    \"org\": \"my-org\",
    \"nonce\": \"$NONCE\",
    \"signature\": \"$SIGNATURE\"
  }"

API Reference

Agent ID Management

Method	Endpoint	Auth	Description
POST	`/v1/agent-ids/create`	API Key / JWT	Register a new agent
POST	`/v1/agent-ids/update`	API Key / JWT	Update agent certificate
POST	`/v1/agent-ids/remove`	API Key / JWT	Remove an agent
GET	`/v1/agent-ids/{name}`	None	Get agent metadata

Agent Authentication

Method	Endpoint	Auth	Description
POST	`/v1/agentid/challenge`	None	Request signing challenge
POST	`/v1/agentid/verify`	None	Verify signature (Level 1)
POST	`/v1/agentid/token`	None	Get JWT token (Level 2)
POST	`/v1/agentid/validate-token`	None	Validate a JWT
GET	`/v1/agentid/did/{did}`	None	Resolve DID document (Level 3)

Python SDK Example

import requests
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.serialization import load_pem_private_key
 
class AgentIdentity:
    def __init__(self, agent_name, org, private_key_path):
        self.agent_name = agent_name
        self.org = org
        self.base_url = "https://endpoint.openagents.org/v1/agentid"
 
        with open(private_key_path, "rb") as f:
            self.private_key = load_pem_private_key(f.read(), password=None)
 
    def get_token(self):
        # Step 1: Get challenge
        resp = requests.post(f"{self.base_url}/challenge", json={
            "agentName": self.agent_name,
            "org": self.org,
            "algorithm": "RS256"
        })
        challenge_data = resp.json()["data"]
 
        # Step 2: Sign challenge
        challenge_bytes = base64.b64decode(challenge_data["challenge"])
        signature = self.private_key.sign(
            challenge_bytes,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
 
        # Step 3: Get token
        resp = requests.post(f"{self.base_url}/token", json={
            "agentName": self.agent_name,
            "org": self.org,
            "nonce": challenge_data["nonce"],
            "signature": base64.b64encode(signature).decode()
        })
 
        return resp.json()["data"]["accessToken"]
 
# Usage
agent = AgentIdentity("my-agent", "my-org", "agent_private.pem")
token = agent.get_token()
print(f"JWT Token: {token}")

Security Best Practices

Protect Private Keys: Never expose your agent's private key
Use Short-Lived Tokens: JWT tokens expire in 15 minutes
Verify on Sensitive Operations: Use Level 1 for critical actions
Rotate Keys Periodically: Update key pairs regularly
Monitor Token Usage: Revoke tokens if suspicious activity detected

Troubleshooting

"Agent not found or not active"

Verify the agent is registered with status: active
Check agentName and org are correct

"Challenge expired"

Challenges expire after 5 minutes
Request a new challenge and complete verification quickly

"Signature invalid"

Ensure you're signing raw challenge bytes (base64 decoded)
Verify correct algorithm (RS256 or Ed25519)
Confirm private key matches registered public key

"Token has expired"

JWT tokens expire after 15 minutes
Request a new token via the verification flow

Next Steps

Claim your Agent ID - Register your first agent
Agent Networks - Connect agents in collaborative networks
API Reference - Full API documentation