agent-id.io

intent

operate against the agent-id.io service to handle self-sovereign AI agent identity. use this skill to register a new agent with Ed25519/X25519 keypair, authenticate with zero-knowledge challenge/response, manage passkeys and rotate keys, verify domain/repo/website ownership, request and approve sponsorships, and look up public agent profiles. triggers on agent identity operations, key management, domain verification, and sponsorship flows.

inputs

external connection: agent-id.io API

• base URL: https://agent-id.io/v1
• auth method: JWT bearer token (obtained via challenge/response auth)
• token TTL: 15 minutes (not refreshable; re-authenticate on expiry)
• setup: no API key required; all auth is cryptographic

local files:

• agent_keys.json: Ed25519 signing key + X25519 encryption key pair (private, keep secret). generated by scripts/keygen.py. required for all agent operations except public profile lookups.
• agent_keys.json.enc: encrypted version of above (AES-256-GCM + scrypt). passphrase stored separately in secret manager or environment variable AGENT_KEY_PASSPHRASE.

python runtime:

• python 3.8+
• dependencies pinned in requirements.txt. run pip-audit before publishing updates.
• venv: python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

agent credentials (from registration):

• agent_id: UUID assigned at registration. required for all authenticated endpoints.
• display_name: agent display name chosen at registration.

external dependencies for verification:

• DNS access (domain TXT verification)
• GitHub/git repo write access + commit ability (code repo verification)
• web server write access (website file verification)

procedure

1. generate keypair locally

inputs: none

step 1a: run keygen script

python3 scripts/keygen.py

outputs:

• agent_keys.json (private keyfile, contains Ed25519 seed + X25519 private key)
• stdout: base64-encoded public keys

step 1b: save agent_keys.json securely (encrypt immediately if possible; see secure key storage)

2. register agent with agent-id.io

inputs:

• public_sign_key (base64 Ed25519 pubkey from step 1a)
• public_enc_key (base64 X25519 pubkey from step 1a)
• display_name (chosen by operator)

step 2a: POST to register endpoint

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>"
  }'

outputs: HTTP 201

{
  "agent_id": "<uuid>",
  "display_name": "my-agent",
  "created_at": "<iso8601>",
  "public_sign_key": "<base64>",
  "public_enc_key": "<base64>"
}

step 2b: save agent_id securely (e.g., env var, config file, secret manager)

3. authenticate and obtain JWT token

inputs:

• agent_id (from step 2a)
• agent_keys.json (private keyfile)

step 3a: request challenge from auth endpoint

AGENT_ID="<your-uuid>"
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'])")

outputs: challenge string (base64, valid 60 seconds)

step 3b: sign challenge locally with private key

python3 scripts/sign_challenge.py "$CHALLENGE" agent_keys.json

outputs: signed_challenge.json (contains agent_id, challenge, signature, timestamp)

step 3c: POST signed challenge to verify endpoint

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'])")

outputs: JWT token (base64, valid 15 minutes)

step 3d: use token in subsequent requests

curl -s https://agent-id.io/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $TOKEN"

4. manage passkeys (add, list, delete)

inputs:

• agent_id
• TOKEN (from step 3c)
• credential_id, public_key, attestation_object (for add passkey; from WebAuthn ceremony)

step 4a (add): POST passkey to endpoint

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>"
  }'

outputs: HTTP 201

{
  "passkey_id": "<uuid>",
  "credential_id": "<base64url>",
  "created_at": "<iso8601>"
}

step 4b (list): GET agent profile

curl -s "https://agent-id.io/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

outputs: agent profile object with passkeys array

step 4c (delete): DELETE specific passkey

curl -s -X DELETE "https://agent-id.io/v1/agents/$AGENT_ID/passkeys/<passkey_id>" \
  -H "Authorization: Bearer $TOKEN"

outputs: HTTP 204 (no content)

5. rotate cryptographic keys

inputs:

• agent_id
• TOKEN (from step 3c)
• agent_keys.json (current private keyfile)

step 5a: generate new keypair and rotation payload

python3 scripts/rotate_keys.py agent_keys.json

outputs:

• new_agent_keys.json (new keypair, same format as original)
• rotation_payload.json (new keys + signature by old private key)

step 5b: POST rotation payload

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

outputs: HTTP 200

{
  "agent_id": "<uuid>",
  "public_sign_key": "<new base64>",
  "public_enc_key": "<new base64>",
  "rotated_at": "<iso8601>"
}

step 5c: replace old keyfile with new

mv new_agent_keys.json agent_keys.json

note: old tokens remain valid until 15-minute expiry. no re-auth required immediately after rotation.

6. verify domain ownership (DNS TXT record)

inputs:

• agent_id
• TOKEN
• domain (e.g., "example.com")

step 6a: start verification (request challenge)

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"}'

outputs: HTTP 200

{
  "record_name": "_agent-id.example.com",
  "expected_txt_value": "agent-id-verification=<value>",
  "status": "pending"
}

step 6b: add DNS TXT record to your domain registrar

• record name: _agent-id.example.com
• record type: TXT
• record value: agent-id-verification=<value> (exact match, case-sensitive)
• allow 2 minutes for DNS propagation

step 6c: check verification (polling)

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"}'

outputs: HTTP 200

{
  "domain": "example.com",
  "status": "verified",
  "verified_at": "<iso8601>"
}

7. verify code repository ownership (GitHub / git repo)

inputs:

• agent_id
• TOKEN
• repo_url (e.g., "https://github.com/org/repo")
• branch (default: main)

step 7a: start verification (request proof value)

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"
  }'

outputs: HTTP 200

{
  "expected_proof_value": "agent-id-verification=<value>",
  "status": "pending"
}

step 7b: create proof file in repository

• file path: .well-known/agent-id-proof.txt (in repo root)
• content: agent-id-verification=<value> (exact match, case-sensitive)
• commit and push to branch specified in step 7a
• wait for GitHub to serve the raw file (usually immediate)

step 7c: check verification

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": "https://raw.githubusercontent.com/org/repo/main/.well-known/agent-id-proof.txt"}'

outputs: HTTP 200

{
  "repo_url": "https://github.com/org/repo",
  "status": "verified",
  "verified_at": "<iso8601>"
}

8. verify website file ownership

inputs:

• agent_id
• TOKEN
• domain (e.g., "example.org")

step 8a: start verification (request proof value)

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"}'

outputs: HTTP 200

{
  "expected_proof_value": "agent-id-verification=<value>",
  "expected_path": "/.well-known/agent-id-verification.txt",
  "status": "pending"
}

step 8b: create proof file on web server

• file path: https://example.org/.well-known/agent-id-verification.txt
• content: agent-id-verification=<value> (exact match, case-sensitive)
• ensure file is accessible via HTTP GET, no authentication required
• allow ~10 seconds for server to serve the file

step 8c: check verification

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"}'

outputs: HTTP 200

{
  "domain": "example.org",
  "status": "verified",
  "verified_at": "<iso8601>"
}

9. request sponsorship

inputs:

• agent_id (requester)
• TOKEN (requester)
• sponsor_agent_id (sponsor's agent UUID)

step 9a: submit sponsorship request

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>"}'

outputs: HTTP 201

{
  "request_id": "<uuid>",
  "requester_agent_id": "<uuid>",
  "sponsor_agent_id": "<uuid>",
  "status": "pending",
  "created_at": "<iso8601>"
}

10. approve sponsorship (sponsor side)

inputs:

• sponsor_agent_id (sponsor)
• SPONSOR_TOKEN (sponsor's JWT)
• requester_public_sign_key (base64, from requester's profile)
• sponsor_agent_keys.json (sponsor's private keyfile)

step 10a (sponsor): fetch pending requests

curl -s https://agent-id.io/v1/sponsorship/requests \
  -H "Authorization: Bearer $SPONSOR_TOKEN"

outputs: HTTP 200

{
  "requests": [
    {
      "request_id": "<uuid>",
      "requester_agent_id": "<uuid>",
      "requester_display_name": "...",
      "created_at": "<iso8601>"
    }
  ]
}

step 10b (sponsor): sign requester's public key with sponsor's private key

python3 scripts/sign_sponsorship.py <requester_public_sign_key_base64> sponsor_agent_keys.json

outputs: sponsorship_signature.txt (base64 Ed25519 signature)

step 10c (sponsor): approve request

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>"}'

outputs: HTTP 200

{
  "request_id": "<uuid>",
  "status": "approved",
  "approved_at": "<iso8601>"
}

11. look up public agent profiles (no auth required)

inputs:

• agent_id (target agent)
• optional: sponsor filter

step 11a: get full agent profile

curl -s "https://agent-id.io/v1/agents/<agent_id>"

outputs: HTTP 200

{
  "agent_id": "<uuid>",
  "display_name": "...",
  "public_sign_key": "<base64>",
  "public_enc_key": "<base64>",
  "verifications": [
    {"type": "domain", "value": "example.com", "verified_at": "..."}
  ],
  "sponsors": ["<sponsor-uuid>"],
  "created_at": "<iso8601>"
}

step 11b (optional): filter agents by sponsor

curl -s "https://agent-id.io/v1/agents?sponsor=<sponsor_agent_id>"

outputs: HTTP 200

{
  "agents": [
    {"agent_id": "...", "display_name": "...", ...}
  ]
}

12. derive SSH and PGP keys from master seed

inputs:

• agent_keys.json (Ed25519 master seed)

step 12a: run derivation script

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)

key hierarchy:

agent_keys.json (Ed25519 seed, 32 bytes)
├── HKDF(info="agent-id/ssh-ed25519") → SSH Ed25519 key
└── HKDF(info="agent-id/pgp-ed25519") → P