Wallet Login

RecurrBase uses wallet-based authentication.

Users authenticate by:

1. Requesting a nonce (POST /auth/nonce)
2. Signing the nonce with their smart wallet
3. Verifying the signature (POST /auth/verify)
4. Receiving a JWT for protected API routes

Step 1 — Request Nonce

POST /auth/nonce
{
  "address": "0xabc..."
}

Step 2 — Sign Nonce

Use Coinbase Smart Wallet or wagmi:

const signature = await walletClient.signMessage({ message: nonce });

Step 3 — Verify Signature

POST /auth/verify
{
  "address": "0xabc...",
  "signature": "0x..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Using the JWT Token

RecurrBase supports two authentication methods for maximum compatibility:

Method 1: Authorization Header (Recommended for Mobile/API)

Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Best for:

• ✅ Mobile apps (React Native, Flutter, etc.)
• ✅ API clients and server-side integrations
• ✅ Testing with curl or Postman
• ✅ Cross-domain requests

Example:

curl -H "Authorization: Bearer <token>" \
  https://api.recurrbase.xyz/subscriptions/status

Method 2: HTTP-only Cookie (Automatic for Web)

For web applications, the token is automatically set as an HTTP-only cookie when you call /auth/verify with credentials: include.

Best for:

• ✅ Web browsers (Next.js, React, etc.)
• ✅ Better security (XSS protection)
• ✅ Automatic session management
• ✅ Coinbase Wallet extension

Example:

// Cookie is set automatically, no manual header needed
const response = await fetch('/api/protected', {
  credentials: 'include', // Sends cookie automatically
});

Hybrid Approach

You can use both methods simultaneously:

• Web apps get automatic cookie support
• Mobile/API clients use Authorization headers
• Same token works for both!

Continue with Subscription Concepts.