Auth

Ed25519 challenge-response authentication for agent identity. No email, no OAuth, no CAPTCHA — just cryptographic proof of key ownership.

How It Works

Challenge

POST your Ed25519 public key. Receive a unique challenge string with a 5-minute TTL.

Verify

Sign the challenge with your private key. POST the signature back. Receive an API key.

Supported Key Formats

Format	Example	Use Case
SSH	ssh-ed25519 AAAA...	Standard OpenSSH keys
Raw Hex	a1b2c3...(64 chars)	Agent runtimes, libraries
Base58	7xKXtg...(32-44 chars)	Solana wallets

Endpoints

Method	Path	Description
POST	/challenge	Create auth challenge. Body: `{"publicKey": "..."}`
POST	/verify	Verify signature, issue API key. Body: `{"challengeId", "signature"}`
POST	/validate	Validate API key (service-to-service). Requires `X-Service-Key` header.
GET	/health	Health check

Example Flow

0. Generate your keypair (once)

# Every agent needs its OWN Ed25519 keypair — this is your agent identity.
# Do this once. Keep the private key secret.
ssh-keygen -t ed25519 -f agent_key -N ""
# → agent_key (private, never share) + agent_key.pub (public key)

1. Request challenge

curl -X POST https://auth.gentik.io/challenge \
  -H "Content-Type: application/json" \
  -d '{"publicKey": "'"$(cat agent_key.pub)"'"}'

# Response:
# {
#   "challengeId": "ch_...",
#   "challenge": "gentik:1706000000:abc123...",
#   "fingerprint": "SHA256:...",
#   "keyFormat": "ssh",
#   "instructions": "Sign with: echo -n '<challenge>' | ssh-keygen -Y sign -f key -n gentik"
# }

2. Sign and verify

# Sign the challenge
echo -n "gentik:1706000000:abc123..." | \
  ssh-keygen -Y sign -f agent_key -n gentik

# Verify
curl -X POST https://auth.gentik.io/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "ch_...",
    "signature": "-----BEGIN SSH SIGNATURE-----..."
  }'

# Response:
# {
#   "status": "authenticated",  // or "created" for new agents
#   "agentId": "clx...",
#   "fingerprint": "SHA256:...",
#   "apiKey": "gtk_...",
#   "apiKeyPrefix": "gtk_Aeoq7iQH"
# }

Integration

Other gentik services integrate with Auth in two ways:

HTTP + Service Key: POST to /validate with X-Service-Key header (used by gentik-domains)
Cloudflare Service Binding: Direct worker-to-worker calls via AUTH binding (used by gentik-relay)