API Reference

Base URL: https://sparkpay.dev

Development: http://localhost:3000

Authentication

Four authentication methods depending on the endpoint type.

Type	Used by	How
None	Public endpoints	No auth required
Stripe signature	Webhook endpoint	Verified via `STRIPE_WEBHOOK_SECRET`
Admin key	App registration	`Authorization: Bearer ${AUTH_SECRET}`
NextAuth session	Dev dashboard API	Google OAuth session cookie

Note

Dev endpoints (/api/dev/*) are blocked in production unless DASHBOARD_ENABLED=true.

Public Endpoints

No authentication required. Available to any client.

GET/api/public/subscription/status-public?email={email}&app_id={app_id}

Check a user's subscription status. No authentication required.

Response (paid user):

{
  "subscription": {
    "status": "active",
    "payment_type": "subscription",
    "is_lifetime": false,
    "current_period_end": "2026-04-14T12:00:00.000Z",
    "cancel_at_period_end": false,
    "billing_interval": "monthly",
    "price_id": "price_xxx",
    "created_at": "2026-03-14T12:00:00.000Z"
  },
  "verified": true,
  "registered": true,
  "usage_count": 42,
  "plan": { "tier": "pro", "name": "Pro", "rank": 1, "features": [...], "limits": {...} },
  "access": { "tier": "pro", "rank": 1, "is_paid": true, "show_paywall": false },
  "tiers": [{ "tier": "free", "rank": 0 }, { "tier": "pro", "rank": 1 }]
}

Tip

For unregistered users: registered: false, subscription: null, plan: null. The access field defaults to free tier.

Protected Endpoints

Requires admin key or Stripe webhook signature.

Dev Dashboard Endpoints

Require NextAuth session with whitelisted email. Blocked in production unless DASHBOARD_ENABLED=true.

Errors & Rate Limits

All endpoints return errors as:

{ "error": "Human-readable message" }

Common status codes:

400

401

404

429

500

Endpoint	Limit
POST /api/public/register-free	5 per email per 30 min
GET /api/public/verify-email	10 per IP per 5 min
POST /api/public/track/page-view	10 per app per IP per 5 min
GET /api/public/recent-activity	30 per IP per min
GET/POST /api/public/usage	Per IP

Ready to ship?

Add Stripe payments to your app in minutes. $99, one-time purchase.

Live demo Get SparkPay