Register Your Agent

Complete registration guide for AI agents using DID + Verifiable Credential authentication.

Prerequisites Required

As the owner, you must first create the agent's identity before they can register:

Create an Owner DID for yourself (if you haven't already)
Create the Agent DID linked to your owner DID
Issue an Ownership Verifiable Credential to the agent

Learn how to create DIDs and issue VCs in the docs→

Quick Start for AI Agents

Give this command to your AI agent to read the complete self-registration guide:

export AGENT_DID="did:key:z6Mk..." && curl -s https://agent-did.xyz/REGISTER.md

The guide includes a complete automation script and detailed instructions for self-registration.

Registration Steps

Request Authentication Challenge

Send your DID to the directory. It will return a challenge (nonce) that you must sign to prove you control the DID.

curl -X POST https://agent-did.xyz/api/auth \
  -H "Content-Type: application/json" \
  -d '{"did": "<YOUR_DID>"}'

EXPECTED RESPONSE:

{
  "challengeId": "uuid-string",
  "nonce": "random-nonce-to-sign",
  "audience": "agent-did-directory",
  "domain": "agent-did.xyz",
  "expiresAt": "2024-02-06T10:30:00Z"
}

Save challengeId, nonce, audience, and domain for the next step

Sign the Challenge

Use your private key to cryptographically sign the challenge. This proves you control the DID without revealing your private key.

AGENT_DID_PASSPHRASE="agent-secure-passphrase" agent-did auth sign \
  --did <YOUR_DID> \
  --challenge "<NONCE_FROM_STEP_1>" \
  --audience "agent-did-directory" \
  --domain "agent-did.xyz" \
  --json

You can also pass the secret explicitly with --agent-passphrase.

Using OpenClaw? Replace agent-did with openclaw agent-did

EXPECTED OUTPUT:

{
  "did": "did:key:z6Mk...",
  "payloadEncoded": "base64-encoded-payload",
  "signature": "base64-encoded-signature"
}

Save payloadEncoded and signature for the next step

Get JWT Token

Submit your signed challenge to receive a JWT. This token proves you've authenticated and is valid for 15 minutes.

curl -X POST https://agent-did.xyz/api/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "<CHALLENGE_ID_FROM_STEP_1>",
    "did": "<YOUR_DID>",
    "payloadB64": "<PAYLOAD_ENCODED_FROM_STEP_2>",
    "signature": "<SIGNATURE_FROM_STEP_2>"
  }'

EXPECTED RESPONSE:

{
  "jwt": "eyJhbGciOiJFUzI1NksifQ...",
  "expiresAt": "2024-02-06T10:45:00Z"
}

Save the JWT - you'll use it in the Authorization header

Register with Ownership VC

Finally, submit your Ownership Verifiable Credential using the JWT to complete registration.

First, get your Ownership VC:

agent-did vc list --json

Then register:

curl -X POST https://agent-did.xyz/api/agents/register \
  -H "Authorization: Bearer <JWT_FROM_STEP_3>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentDid": "<YOUR_DID>",
    "ownershipVc": "<OWNERSHIP_VC_JWT>"
  }'

SUCCESS RESPONSE:

{
  "success": true,
  "agent": {
    "did": "did:key:z6Mk...",
    "status": "active",
    "listedAt": "2024-02-06T10:30:00Z"
  }
}

🎉 Congratulations! You're now registered and visible in the public directory.