Core Concept
Ed25519 Security
Why We Don't Use API Keys
The Philosophy
"Don't share secrets. Prove identity."
The Problem with API Keys
API Keys
- ✗Shared secret (both sides know it)
- ✗If leaked, attacker has full access
- ✗Logged in plaintext everywhere
- ✗No way to verify sender's identity
Ed25519 Signatures
- ✓Private key never shared
- ✓Public key can't decrypt anything
- ✓Signatures are unique per request
- ✓Cryptographic proof of identity
How It Works
1
Client Agent
Sender Signs
Signs the JSON payload with their Private Key
signature = private_key.sign(payload)2
Your API
Receiver Verifies
Verifies the signature using the Sender's Public Key (fetched from Registry)
is_valid = public_key.verify(signature, payload)3
Your API
Decision
If valid → process request. If invalid → reject (401)
if is_valid: process() else: reject()Why Ed25519?
Fast
10x faster than RSA
Small Signatures
Only 64 bytes
Secure
Resistant to side-channel attacks
Industry Standard
Ed25519 is used by SSH, Signal, and most modern cryptographic systems. It's battle-tested and trusted by security experts worldwide.
Example Flow
Client (Sender) Your API (Receiver)
│ │
│ 1. Create payload │
│ {"intent": "book_table"} │
│ │
│ 2. Sign with PRIVATE key │
│ sig = sign(payload, priv_key) │
│ │
│ 3. Send request │
├───────────────────────────────────>│
│ Headers: X-Agent-Signature │
│ Body: payload │
│ │
│ │ 4. Fetch PUBLIC key
│ │ (from Registry)
│ │
│ │ 5. Verify signature
│ │ verify(sig, payload, pub_key)
│ │
│ │ 6. If valid → process
│<───────────────────────────────────│ If invalid → reject
│ 200 OK │
│ │🔒 Security Guarantee
Even if someone intercepts the request, they cannot forge a signature without the sender's private key. This makes man-in-the-middle attacks impossible.