API Design Best Practices for Tor Hidden Services

API authentication for .onion services cannot rely on IP-based access control (all connections appear from 127.0.0.1 via the Tor daemon). Instead, use cryptographic authentication. For machine-to-machine APIs, issue API keys (256-bit random values) that clients include in request headers as Authorization: Bearer . For user-facing APIs, implement JWT (JSON Web Token) authentication with Ed25519 signatures, providing compact and verifiable identity tokens without IP dependency. For zero-knowledge authentication (clients prove they have a valid credential without revealing which credential), implement SRP (Secure Remote Password) or similar zero-knowledge proof protocols at the authentication layer.

Standard IP-based rate limiting is ineffective for .onion service APIs because all traffic originates from the Tor process on localhost. Implement rate limiting at the account/API key level: track request counts per API key or JWT session in Redis with TTL. For unauthenticated API endpoints, implement proof-of-work challenges (hashcash or similar) before returning API responses, adding computational cost per request without requiring user identification. For public APIs where proof-of-work is too friction-heavy, implement response caching aggressively and accept higher abuse risk as a tradeoff for accessibility. Monitor abnormal request patterns (rapid sequential requests from authenticated accounts) and implement account-level circuit breakers.

Tor circuits add 100-600ms base latency to each API request. API designs that require multiple sequential requests (waterfall patterns) multiply this latency, creating unusably slow applications. Design APIs to be batch-friendly: allow clients to fetch multiple related resources in a single request. GraphQL is particularly valuable for .onion service APIs because clients can specify exactly what data they need in a single query, eliminating the over-fetching and multiple-round-trip problems of REST APIs. Implement long-polling or WebSocket connections (with appropriate security level caveats) for applications needing real-time updates, reducing the need for repeated polling that compounds circuit latency.

API responses for privacy-focused services should minimize data leakage through metadata. Return only requested fields - avoid including system identifiers, server timestamps, or internal IDs that could fingerprint users across sessions. Use opaque identifiers (random UUIDs) rather than sequential integers that reveal database insert order and allow inference of user count or activity level. Normalize timestamps to coarser granularity (minute-level rather than millisecond-level) to prevent timing correlation attacks. For content delivery, stream responses when possible to prevent response size fingerprinting. Implement consistent response times for authentication failures (simulate processing time equivalent to successful authentication) to prevent timing oracle attacks on credential validation.

Error responses in .onion service APIs should be generic enough to not reveal system architecture details. Return consistent HTTP 400 for all invalid request formats rather than specific error messages that reveal backend validation logic. Implement CORS restrictions: configure Access-Control-Allow-Origin to your specific .onion domain rather than wildcard, preventing cross-origin requests from other .onion services. Set security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Content-Security-Policy appropriate for your API consumers. For JSON APIs, ensure all responses include Content-Type: application/json to prevent MIME-type sniffing vulnerabilities. Log authentication failures with rate monitoring to detect credential stuffing attacks.