L402 Authentication

Lightning-native API authentication for Lightning Faucet endpoints

Overview

L402 (formerly LSAT) is an HTTP authentication protocol that uses Lightning Network payments as proof of access. Instead of API keys, you pay a small Lightning invoice and receive a macaroon token that grants access to the API.

How It Works

Request: Make an HTTP request to an L402-protected endpoint without credentials.
Challenge: The server responds with HTTP 402 Payment Required and a WWW-Authenticate header containing a base64 token and a Lightning invoice.
Pay: Pay the Lightning invoice using any Lightning wallet.
Retry: Repeat the request with an Authorization header containing the token and payment preimage.
Access: The server validates the payment and returns the API response.

Authorization Header Format

Authorization: L402 <token>:<preimage>

Where:

<token> is the base64 credential from the token parameter of the WWW-Authenticate header (the JSON body's token and macaroon fields are identical)
<preimage> is the 64-character hex payment preimage obtained after paying the invoice

Important: The header prefix is L402 (not Bearer). The legacy prefix LSAT is also accepted.

402 Response Headers

When you hit a protected endpoint without valid credentials, the response includes:

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 version="0", token="<base64>", invoice="<bolt11>"

Example Flow

1. Initial Request (no auth)

curl -X POST https://lightningfaucet.com/api/l402/fortune

2. Parse the 402 Response

# Response headers contain:
# WWW-Authenticate: L402 version="0", token="eyJpZG...", invoice="lnbc..."
#
# Extract the token and invoice parameters (or read the token/macaroon
# and invoice fields in the JSON body; token and macaroon are identical)

3. Pay the Invoice

# Pay the bolt11 invoice with your Lightning wallet
# Save the payment preimage (64 hex chars)

4. Retry with L402 Auth

curl -X POST https://lightningfaucet.com/api/l402/fortune \
  -H "Authorization: L402 eyJpZG...:abc123def456..."

Available Endpoints

/api/l402/fortune - Random fortune (50 sats standard, 100 premium)
/api/l402/joke - Random joke (50 sats standard, 100 premium)
/api/l402/quote - Random quote (10 sats standard, 30 premium)
/api/l402/registry_submit - Submit an API to the registry (1,000 sats)

Common Issues

`invalid_auth_format`

The Authorization header must exactly match: L402 <token>:<preimage>

One space between L402 and the token
Token must be valid base64 (characters: A-Za-z0-9+/=)
Colon separator between token and preimage
Preimage must be exactly 64 hex characters (a-f0-9)
No URL-encoding of the base64 characters

`invalid_token`

The token signature doesn't match or the payment hash doesn't correspond to the preimage. Ensure you're using the token from the original 402 response paired with the preimage from that same payment.

Libraries & Tools

lightning-wallet-mcp - MCP server with built-in L402 support
l402 (Rust) - Rust L402 client library
Any HTTP client + Lightning wallet can implement L402 manually