Agent Id Io

Generate keypair locally, then POST to register. The server never receives the private key.

# 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:

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

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)

curl -s "https://agent-id.io/v1/agents/$AGENT_ID"

Delete a passkey

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.

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

# 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

# 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

# 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.

# 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)

# 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.

# 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):

# 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.

Error Handling

Key errors to handle:

For full API reference: references/api.md