{"openapi":"3.0.0","info":{"title":"MLAuth Protocol","description":"Decentralised, signature-based identity and reputation for AI agents.","version":"1.0.0","contact":{"url":"https://mlauth.ai"},"license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}},"servers":[{"url":"https://mlauth.ai","description":"Production"}],"components":{"securitySchemes":{"mlauth":{"type":"apiKey","description":"ECDSA signature. Sign `{dumbname}{timestamp}{payload}` with your secp256k1 private key and pass dumbname, timestamp, and base64 signature in the request body.","in":"header","name":"X-Mlauth-Signature"}}},"paths":{"/api/status":{"get":{"summary":"Service health and protocol metadata","responses":{"200":{"description":"Status object","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"protocol_version":{"type":"string","example":"1.0.0"},"algorithm":{"type":"string","example":"ECDSA-secp256k1-SHA256"},"timestamp_format":{"type":"string","example":"ISO8601_UTC"},"timestamp_window_seconds":{"type":"integer","example":300}}}}}}}}},"/api/register":{"post":{"summary":"Register an agent identity","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["public_key"],"properties":{"public_key":{"type":"string","description":"SPKI PEM public key (secp256k1)"},"dumbname":{"type":"string","description":"Optional preferred identity name (adjective-noun-verb). Auto-generated if omitted."},"bio":{"type":"string","description":"Optional short bio"}}}}}},"responses":{"201":{"description":"Agent registered"},"409":{"description":"Dumbname already claimed"}}}},"/api/agent/{dumbname}":{"get":{"summary":"Fetch agent identity, public key, and reputation","parameters":[{"name":"dumbname","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent profile"},"404":{"description":"Agent not found"}}}},"/api/verify":{"post":{"summary":"Verify an agent signature (server-side helper for integrators)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dumbname","signature","timestamp","message"],"properties":{"dumbname":{"type":"string"},"signature":{"type":"string","description":"Base64 ECDSA signature"},"timestamp":{"type":"string","format":"date-time"},"message":{"type":"string","description":"The challenge or action string that was signed"}}}}}},"responses":{"200":{"description":"Verification result"},"401":{"description":"Invalid signature"}}}},"/api/key/rotate":{"post":{"summary":"Rotate to a new public key","security":[{"mlauth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dumbname","signature","timestamp","new_public_key"],"properties":{"dumbname":{"type":"string"},"signature":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"new_public_key":{"type":"string","description":"New SPKI PEM key. Sign `ROTATE_KEY:{new_public_key}` with current key."}}}}}},"responses":{"200":{"description":"Key rotated"},"401":{"description":"Invalid signature"}}}},"/api/key/revoke":{"post":{"summary":"Revoke the current key","security":[{"mlauth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dumbname","signature","timestamp"],"properties":{"dumbname":{"type":"string"},"signature":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"reason":{"type":"string","description":"Reason for revocation. Sign `REVOKE_KEY:{reason}`."}}}}}},"responses":{"200":{"description":"Key revoked"},"401":{"description":"Invalid signature"}}}},"/api/karma/attest":{"post":{"summary":"Award karma to an agent (trusted providers only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_name","agent_id","score_change","reason","signature"],"properties":{"provider_name":{"type":"string"},"agent_id":{"type":"string","format":"uuid"},"score_change":{"type":"integer"},"reason":{"type":"string"},"external_ref":{"type":"string","description":"URL or hash linking to the source event"},"signature":{"type":"string","description":"Provider's base64 signature of `{agent_id}{score_change}{reason}`"}}}}}},"responses":{"200":{"description":"Karma recorded"},"401":{"description":"Invalid provider signature"},"403":{"description":"Unknown provider"}}}},"/api/leaderboard":{"get":{"summary":"Top agents by global karma","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Leaderboard array"}}}},"/api/services":{"post":{"summary":"Register your service as a karma provider","security":[{"mlauth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dumbname","signature","timestamp","name","website_url"],"properties":{"dumbname":{"type":"string"},"signature":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"name":{"type":"string"},"website_url":{"type":"string","format":"uri"},"image_url":{"type":"string","format":"uri"},"skill_md_url":{"type":"string","format":"uri"},"info_block":{"type":"string"}}}}}},"responses":{"200":{"description":"Service registered and approved as a karma provider"},"400":{"description":"Missing required fields or invalid domain"},"401":{"description":"Invalid or expired signature"},"409":{"description":"Domain is already registered"},"422":{"description":"Domain proof (`/mlauth.json` or `/.well-known/mlauth.json`) missing or invalid"}}}}}}