DIDAuth for Agent

Use nuwa-id and did-check to run a practical DIDAuth flow in agent environments.

This guide shows a simple DIDAuth flow for agent environments:

1. Agent generates a local key.
2. Agent sends a deep link to the user.
3. User authorizes the key on id.nuwa.dev and sends back DID text.
4. Agent verifies key binding and sends DID-authenticated requests.

The flow uses:

• nuwa-id CLI from @nuwa-ai/identity-kit
• did-check service at https://did-check.nuwa.dev

Prerequisites

• Node.js 18+
• Access to Rooch mainnet

Install CLI

npm i -g @nuwa-ai/identity-kit
nuwa-id help

Agent Skill

If the user can provide a direct skill prompt to the agent, share:

• https://id.nuwa.dev/skill.md

In many agent environments, this is the fastest path: user sends this link to the agent, and the agent follows the skill instructions directly.

Step 1: Initialize local key material

nuwa-id init --key-fragment support-agent-main

This creates local state under ~/.config/nuwa-did:

• config.json
• keys/default.json

Any file under keys/ is private key material. Do not share it.

Step 2: Generate deep link for user authorization

nuwa-id link

Send the printed URL to the user.
The user opens the link in a browser, logs in on id.nuwa.dev, and approves adding the agent key.

Step 3: Collect DID from user

After approval, the user sends DID text back to the agent, for example:

did:rooch:rooch1...

Step 4: Persist DID and verify key binding

Save DID into active profile:

nuwa-id set-did --did did:rooch:rooch1...

Verify active profile key binding:

nuwa-id verify

Continue only when verification succeeds.

Step 5: Send DID-authenticated request

With the DID saved and key verified, you can now send a DID-authenticated request.

Generate header only:

nuwa-id auth-header \
  --method GET \
  --url https://did-check.nuwa.dev/whoami

Or send directly:

nuwa-id curl \
  --method GET \
  --url https://did-check.nuwa.dev/whoami

Expected response:

{
  "ok": true,
  "did": "did:rooch:rooch1..."
}

Defaults

• Network: main
• CADOP domain: https://id.nuwa.dev
• Key fragment: loaded from active profile in config

Optional: manage profiles

nuwa-id profile create --name support-b --key-fragment support-agent-b
nuwa-id profile list
nuwa-id profile use --name support-b

Troubleshooting

• agent key not initialized: run nuwa-id init
• did is not set: run nuwa-id set-did --did DID
• verification method not found: user has not authorized the agent key yet, or sent the wrong DID
• 401 Unauthorized from /whoami: regenerate auth header and ensure URL/method match exactly

If --key-fragment is omitted on nuwa-id init, the CLI generates a timestamp-based fragment.