🛡️ 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

Create a "Kind 27235" event.

Sign it with your Nostr Private Key (nsec).

Base64-encode the signed event JSON.

Pass it in the header as: Authorization: Nostr [base64_encoded_event]

Generation Script (Bash + nostr-tool)

🔒 3. Rate Limiting Strategy

Our API uses a two-layer rate-limiting system to protect the network.

Layer 1: Cloudflare WAF (Burst Limiter)

A blanket rule across all /api/public/* paths:

Limit: 10 requests per 10 seconds per IP

Action: Block (with 10s mitigation timeout)

Purpose: Prevents rapid bursts and DDoS attacks

Layer 2: Application Rate Limits (Per-Endpoint)

Each endpoint has its own limit enforced at the application layer:

Endpoint	Limit	Per
`GET /servers`	60/min	IP
`POST /create`	10/min	IP
`POST /claim`	10/min	IP
`GET /{paymentHash}`	60/min	IP
`POST /status`	30/min	IP
`POST /renew`	20/min	IP
`POST /bandwidth-reset`	10/min	IP
`POST /{paymentHash}/sync`	5/min	Subscription
`GET /list`	30/min	Account
`POST /ping/lookup`	5/min	IP
`POST /ping/test`	3/min	IP

Handling 429 Responses

When you receive an ERR_RATE_LIMIT_EXCEEDED (429), your application MUST implement exponential backoff:

🔑 1. API Keys (Bearer Token)#

Best Practices#

💜 2. Nostr Auth (NIP-98)#

How it works#

Generation Script (Bash + nostr-tool)#

🔒 3. Rate Limiting Strategy#

Layer 1: Cloudflare WAF (Burst Limiter)#

Layer 2: Application Rate Limits (Per-Endpoint)#

Handling 429 Responses#