🛡️ Security & Authentication
TunnelSats provides two primary ways to authenticate your requests. Understanding which one to use depends on whether you are building a centralized service or a privacy-first Nostr integration.
🔑 1. API Keys (Bearer Token)#
API Keys are the simplest way to authenticate and are recommended for most backend integrators.Format: sk_live_[random_string]
Header: Authorization: Bearer sk_live_...
Best Practices#
Never expose your API key in client-side code (Frontend).
Store keys in environment variables (.env.local).
Rotate your keys immediately if you suspect a leak.
💜 2. Nostr Auth (NIP-98)#
For users who want to stay anonymous or integrate directly with the Nostr ecosystem, we support NIP-98 (HTTP Authentication for Nostr).How it works#
1.
Create a "Kind 27235" event.
2.
Sign it with your Nostr Private Key (nsec).
3.
Base64-encode the signed event JSON.
4.
Pass it in the header as: Authorization: Nostr [base64_encoded_event]
🔒 3. Rate Limiting Strategy#
Our API uses a tiered rate-limiting system to protect the network.Bearer Auth: Higher limits (linked to your account status).
NIP-98 Auth: Standard public limits.
Unauthenticated: Low limits (per IP).
Handling 429 Responses#
When you receive an ERR_RATE_LIMIT_EXCEEDED (429), your application MUST stop polling for at least the number of seconds specified in the Retry-After header. Modified at 2026-04-12 13:23:50
