Skip to main content

Using with an Existing Backend

When VITE_BACKEND=custom, the extension talks to your own API instead of Supabase or Firebase. Authentication is done by reading a session cookie from your domain.

Setup​

  1. Set environment variables:
VITE_BACKEND=custom
VITE_CUSTOM_API_URL=https://api.yourapp.com
VITE_CUSTOM_COOKIE_DOMAIN=https://app.yourapp.com
VITE_CUSTOM_COOKIE_NAME=session
  1. Add your cookie domain to the extension manifest:
{
  "optional_permissions": ["tabs", "cookies"],
  "optional_host_permissions": ["https://app.yourapp.com/*"]
}

Replace app.yourapp.com with the domain where your app sets the session cookie. For policy rules on optional permissions, see Manifest Permissions.

Local Development​

Point VITE_CUSTOM_API_URL at your local API (e.g. http://localhost:3000). Set VITE_CUSTOM_COOKIE_DOMAIN to the origin where your app runs (e.g. http://localhost:5173). Add that origin to optional_host_permissions in the manifest. Run pnpm build:chrome to assemble the extension and load it in Chrome/Firefox.

Auth Flow​

  1. User logs in on your website (your domain).
  2. Your backend sets a session cookie (e.g. session).
  3. The extension reads that cookie via the Cookies API.
  4. The extension calls GET {apiBaseUrl}/auth/me with the cookie in the Cookie header.
  5. Your API validates the cookie and returns { id, email }.
  6. If valid, the user is considered logged in.

If the cookie is missing or invalid, the extension shows “Please log in on your website first” with a link to cookieDomain.

Required API Endpoint​

Implement GET /auth/me (or your chosen path) that:

  • Accepts the session cookie in the request
  • Returns { id: string, email: string } on success
  • Returns 401 or invalid response when the session is invalid

Stripe Contract (Billing)​

For checkout and portal, the extension calls your API with the same logical contracts as Supabase/Firebase:

ActionMethodPath (convention)Payload
CheckoutPOSTstripe-checkout{ email, subType }
PortalPOSTstripe-manage-subscription{ customerId }

Your API can use different paths by setting VITE_CUSTOM_API_URL to include the base path (e.g. https://api.yourapp.com/billing). The extension appends the function name: {apiBaseUrl}/stripe-checkout, {apiBaseUrl}/stripe-manage-subscription.

Expected responses:

  • Checkout: { url: string } (Stripe Checkout URL) or { error: string }
  • Portal: { url: string } (Stripe Customer Portal URL) or { error: string }

No Extension Login​

In custom mode, the extension does not provide email/password forms. Users must log in on your website. The cookie is the only auth mechanism.