OpenClaw skill for the agent-id.io identity and trust service. Use it to register an AI agent, authenticate with challenge/response, manage passkeys and cryp...
---
name: agent-id-io
version: "1.0.2"
description: >
OpenClaw skill for the agent-id.io identity and trust service. Use it to
register an AI agent, authenticate with challenge/response, manage passkeys
and cryptographic keys, verify domains/repos/websites, handle sponsorships,
and inspect public agent profiles. Triggers on: "agent-id.io", "register
agent identity", "authenticate agent", "rotate agent keys", "verify agent
identity", and "agent sponsorship".
---
# agent-id.io
**What it is:** OpenClaw skill for operating against the `agent-id.io` service. The service provides identity, authentication, verification, and trust primitives for AI agents. Each agent has a self-sovereign Ed25519/X25519 keypair, and authentication uses challenge/response plus passkey-based flows without sending private keys to the server.
**Base URL:** `https://agent-id.io/v1`
## Setup (pinned dependencies)
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
Dependency policy:
- Runtime dependencies are pinned in `requirements.txt`
- If you maintain this skill, run `pip-audit` and your preferred test flow before publishing updates
---
## 1. Register a New Agent
Generate keypair locally, then POST to register. The server never receives the private key.
```bash
# Generate Ed25519 signing key + X25519 encryption key
python3 scripts/keygen.py
# → Outputs: agent_keys.json (private, keep secret) + public keys as base64
# Register
curl -s -X POST https://agent-id.io/v1/agents/register \
-H "Content-Type: application/json" \
-d '{
"display_name": "my-agent",
"public_sign_key": "<base64 Ed25519 pubkey>",
"public_enc_key": "<base64 X25519 pubkey>"
}'
# → { "agent_id": "uuid", "display_name": "...", "created_at": "..." }
```
**Save the `agent_id` and `agent_keys.json` securely.** Lost private key = lost identity.
---
## 2. Authenticate (Get a Token)
Authentication is a two-step challenge/response:
```bash
AGENT_ID="<your-uuid>"
# Step 1: Get challenge
CHALLENGE=$(curl -s -X POST https://agent-id.io/v1/auth/challenge \
-H "Content-Type: application/json" \
-d "{\"agent_id\": \"$AGENT_ID\"}" | python3 -c "import json,sys; print(json.load(sys.stdin)['challenge'])")
# Step 2: Sign challenge + verify
python3 scripts/sign_challenge.py "$CHALLENGE" agent_keys.json
# → Outputs the auth/verify payload as JSON
# POST the signed payload
TOKEN=$(curl -s -X POST https://agent-id.io/v1/auth/verify \
-H "Content-Type: application/json" \
-d "$(cat signed_challenge.json)" | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")
```
Token is a JWT, valid 15 minutes, not refreshable. Re-authenticate when expired.
**Usage:** `Authorization: Bearer $TOKEN`
---
## 3. Manage Passkeys
Passkeys = the WebAuthn credentials tied to your agent's public key. Free tier: 2 passkeys max.
### Add a passkey
```bash
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/passkeys" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"credential_id": "<base64url>",
"public_key": "<base64url>",
"attestation_object": "<base64url>"
}'
```
### List passkeys (via agent profile)
```bash
curl -s "https://agent-id.io/v1/agents/$AGENT_ID"
```
### Delete a passkey
```bash
curl -s -X DELETE "https://agent-id.io/v1/agents/$AGENT_ID/passkeys/<passkey_id>" \
-H "Authorization: Bearer $TOKEN"
# 204 No Content on success
# 409 last_passkey → cannot delete the only remaining passkey
```
---
## 4. Rotate Cryptographic Keys
Use when private key is compromised or as routine hygiene. Requires signing new key with old private key.
```bash
python3 scripts/rotate_keys.py agent_keys.json
# → Generates new_agent_keys.json + rotation_payload.json
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/keys/rotate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "$(cat rotation_payload.json)"
# → { "agent_id": "...", "public_sign_key": "<new>", "rotated_at": "..." }
```
After rotation: replace `agent_keys.json` with `new_agent_keys.json`. Old tokens are still valid until expiry.
---
## 5. Verify Identity
Three verification methods — all start a pending verification, then a check call resolves it.
### Domain TXT verification
```bash
# Start verification
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/verify/domain" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com"}'
# → { record_name: "_agent-id.example.com", expected_txt_value: "agent-id-verification=..." }
# Add DNS TXT record, then check
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/verify/domain/check" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com"}'
```
### Code repository
```bash
# Start: provide repo URL + proof file URL
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/verify/code-repo" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"repo_url": "https://github.com/org/repo", "proof_url": "https://raw.githubusercontent.com/org/repo/main/.well-known/agent-id-proof.txt"}'
# → { expected_proof_value: "agent-id-verification=..." }
# Create .well-known/agent-id-proof.txt with exact value, commit, then check
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/verify/code-repo/check" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"proof_url": "..."}'
```
### Website file
```bash
# Start
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/verify/website-file" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"domain": "example.org"}'
# → Proof file expected at https://example.org/.well-known/agent-id-verification.txt
# Create file with exact expected value, then check
curl -s -X POST "https://agent-id.io/v1/agents/$AGENT_ID/verify/website-file/check" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"domain": "example.org"}'
```
---
## 6. Sponsorship
Sponsorship = cryptographic vouching. Sponsor signs the sponsored agent's public key.
```bash
# Request sponsorship from a known agent
curl -s -X POST https://agent-id.io/v1/sponsorship/request \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sponsor_agent_id": "<sponsor-uuid>"}'
# Sponsor: view pending requests
curl -s https://agent-id.io/v1/sponsorship/requests \
-H "Authorization: Bearer $SPONSOR_TOKEN"
# Sponsor: approve (sign requester's public_sign_key with your private key)
python3 scripts/sign_sponsorship.py <requester_public_sign_key_base64> agent_keys.json
curl -s -X POST "https://agent-id.io/v1/sponsorship/requests/<request_id>/approve" \
-H "Authorization: Bearer $SPONSOR_TOKEN" -H "Content-Type: application/json" \
-d '{"sponsor_signature": "<base64 Ed25519 sig>"}'
```
---
## 7. Look Up Agents (Public, No Auth)
```bash
# Get agent profile
curl -s "https://agent-id.io/v1/agents/<agent_id>"
# Get agent's public keys
curl -s "https://agent-id.io/v1/agents/<agent_id>/keys"
# List agents sponsored by a specific agent
curl -s "https://agent-id.io/v1/agents?sponsor=<sponsor_agent_id>"
```
---
## 8. Derive SSH + PGP Keys from Master Seed
The Ed25519 master seed is the single source of truth. All other keys are derived deterministically — **one backup covers everything**.
```bash
# Derive SSH + PGP keys from agent_keys.json master seed
python3 scripts/derive_keys.py agent_keys.json --out-dir ~/.ssh
# Outputs:
# ~/.ssh/id_agent_ed25519 (SSH private key, OpenSSH format, chmod 600)
# ~/.ssh/id_agent_ed25519.pub (SSH public key)
# ~/.ssh/agent_pgp_private.asc (PGP private key, ASCII-armored)
# ~/.ssh/agent_pgp_public.asc (PGP public key)
# Import PGP key to GPG keyring
gpg --import ~/.ssh/agent_pgp_private.asc
```
**Key hierarchy:**
```
master_seed (Ed25519 seed, 32 bytes)
├── HKDF(info="agent-id/ssh-ed25519") → SSH Ed25519 key
└── HKDF(info="agent-id/pgp-ed25519") → PGP Ed25519 key
```
Keys are deterministic: the same `agent_keys.json` always produces the same SSH + PGP keys. Safe to regenerate anytime from backup.
---
## 9. Secure Key Storage
The agent is responsible for keeping the master keyfile secure. Treat `agent_keys.json` like a private key — it IS one.
Security warning: inline environment variable assignments like `AGENT_KEY_PASSPHRASE=... python3 ...` are less safe. They can be exposed through `/proc/<pid>/environ`, shell history, process logging, or terminal scrollback.
**Encrypt the keyfile (AES-256-GCM + scrypt):**
```bash
# Encrypt (preferred: interactive prompt, avoids exposing the passphrase inline)
python3 scripts/secure_keyfile.py encrypt agent_keys.json
# → creates agent_keys.json.enc
rm agent_keys.json # delete plaintext
# Decrypt on use (preferred: interactive prompt)
python3 scripts/secure_keyfile.py decrypt agent_keys.json.enc --out /tmp/keys.json
python3 scripts/authenticate.py /tmp/keys.json --save-token /tmp/agent_token.jwt
rm /tmp/keys.json /tmp/agent_token.jwt # delete immediately after use
# Less safe fallback: passphrase via environment variable
AGENT_KEY_PASSPHRASE="<strong-passphrase>" python3 scripts/secure_keyfile.py encrypt agent_keys.json
AGENT_KEY_PASSPHRASE="<strong-passphrase>" python3 scripts/secure_keyfile.py decrypt agent_keys.json.enc --out /tmp/keys.json
```
**Where the passphrase lives:**
- A secret manager you already trust
- An environment variable injected at runtime, for example `AGENT_KEY_PASSPHRASE`
- Never hardcoded, never in config files, never in git
**Storage pattern:**
- Keep `agent_keys.json.enc` as the portable encrypted artifact
- Store the passphrase separately from the encrypted file
- If you sync backups offsite, encrypt first and verify restore steps periodically
**Backup strategy:**
- The encrypted `agent_keys.json.enc` can be stored anywhere you already trust for encrypted backups
- The passphrase must be stored separately from the keyfile
- Losing both = permanent identity loss
---
## Scripts
All scripts are in `scripts/`. See each file's header for usage.
| Script | Purpose |
|--------|---------|
| `scripts/register.py` | Full registration incl. PoW challenge/solve |
| `scripts/authenticate.py` | Auth flow → JWT token (`--save-token` or `--print-token`) |
| `scripts/keygen.py` | Generate Ed25519 + X25519 keypair → `agent_keys.json` |
| `scripts/sign_challenge.py` | Sign auth challenge manually → `signed_challenge.json` |
| `scripts/rotate_keys.py` | Generate new keypair + rotation signature |
| `scripts/sign_sponsorship.py` | Sign requester's pubkey for sponsorship approval |
| `scripts/derive_keys.py` | Derive SSH + PGP keys from master seed (HKDF) |
| `scripts/secure_keyfile.py` | Encrypt/decrypt agent_keys.json (AES-256-GCM + scrypt) |
---
## Error Handling
Key errors to handle:
| Error | Meaning | Action |
|-------|---------|--------|
| `409 conflict` | Key already registered | Generate new keypair |
| `409 passkey_limit_reached` | Free tier: max 2 passkeys | Delete old or upgrade |
| `409 last_passkey` | Cannot delete last passkey | Add another first |
| `403 agent_revoked` | Identity revoked | Call `POST /agents/{id}/unrevoke` |
| `400 invalid_challenge` | Challenge expired (>60s) | Re-fetch challenge |
| `401 unauthorized` | Token expired or invalid | Re-authenticate |
For full API reference: `references/api.md`
don't have the plugin yet? install it then click "run inline in claude" again.