Requirements

What you need to know before deciding if Key-Rex will work for your website

Overview

Before you decide to use Key-Rex, it's important to understand what you'll need. Most of these requirements are simple, but there's one critical requirement that's essential for Key-Rex to work: you need a backend server or serverless function.

⚠️ Critical Requirement

You must have a backend server or serverless function for Key-Rex to work. This is the one requirement that can't be skipped. If you only have a static website with no backend, you'll need to add a serverless function. See the Backend Requirements section below for details and examples.

📋 Getting Started

To use Key-Rex, you'll need to create a Key-Rex account first. After signing in with your Lightning wallet, you'll get a unique siteId and integration code from your dashboard. This siteId is included in your integration code and identifies your website to the Key-Rex service.

⚠️

Backend Requirements(REQUIRED - NOT OPTIONAL)

⚠️ Backend endpoint is REQUIRED - not optional

Adding the button to your website is easy—just two lines of code. But for visitors to actually sign in, you need a backend server (or serverless function) that receives the sign-in information and signs them into your website. Without this, visitors can click the button, but nothing will happen.

What happens without a backend: The button appears on your website, but when someone clicks it, the sign-in process can't complete because there's nowhere to send the authentication information. It's like having a doorbell with no one to answer the door.

What Your Backend Needs to Do

Your backend code needs to handle a few simple tasks:

  • Receive the visitor's unique identifier (called an xpub) when they sign in
  • Sign them into your website (create a session or login token)
  • Optionally link this identifier to their existing account in your system (see dashboard Documentation tab for complete examples)
  • If you want to support multiple wallets per user, optionally store an array of xpubs (or a separate user_wallets table) so more than one wallet can unlock the same account.
  • Send them to the right page on your website after they sign in

How Your Backend Receives the xpub

The xpub can be delivered to your backend in several ways:

  • onSuccess callback: Set window.Key-Rex.onSuccess = function(xpub) { ... } to receive xpub directly
  • URL parameter: After QR code authentication, xpub is appended to your return URL as ?xpub=...
  • Cookies: xpub may be stored in cookies (format: keyrex_xpub_<prefix>) for cross-domain scenarios
  • postMessage: When using popup authentication, xpub is sent via window.postMessage() from the popup window

See the dashboard Documentation tab for complete code examples showing how to handle each method.

What Counts as a Backend?

Any of these options will work:

  • A traditional server running code (Node.js, Python, PHP, Ruby, etc.)
  • Serverless functions (Vercel Functions, AWS Lambda, Google Cloud Functions, Netlify Functions)
  • Edge functions (Cloudflare Workers, Vercel Edge Functions)
  • API routes if you're using a framework like Next.js, Nuxt.js, or similar

If you're not sure which one applies to you, check our documentation or FAQ for examples that match your setup.

What If I Only Have a Static Website?

If your website is completely static (like GitHub Pages, Netlify static hosting, or Vercel static), you can still use Key-Rex! You'll just need to add a serverless function to handle the sign-in process. Many hosting providers make this easy to set up, and we provide examples in the dashboard documentation.

See FAQ for static site examples, or check the dashboard Documentation tab after signup for code examples.

🌐Browser Requirements

  • • Modern browser with JavaScript enabled
  • • Works on all major browsers (Chrome, Firefox, Safari, Edge)
  • • Mobile browsers supported (iOS Safari, Chrome Mobile)
  • • No browser extensions required for users

💻Framework Compatibility

  • • Works with any framework (React, Vue, Angular, etc.)
  • • Compatible with all CMS platforms (WordPress, Drupal, etc.)
  • • Plain HTML/JavaScript supported
  • • Server-side rendering (SSR) compatible

📱User Requirements

For someone to sign in with Key-Rex, they need to have a Lightning wallet app on their phone or computer. If they don't have one, they won't be able to use this sign-in method. Key-Rex can work as a standalone sign-in option, and we recognize that many websites already have existing login processes. In these cases, Key-Rex works great as an alternative authentication method, allowing you to offer both options simultaneously so visitors can choose what works for them.

  • Users need a compatible Lightning wallet
  • Desktop: A browser extension wallet
  • Mobile: A mobile wallet app
  • All wallets are free to download and use

Note: Key-Rex can work as a standalone sign-in option, and we recognize that many websites already have existing login processes. In these cases, Key-Rex works great as an alternative authentication method, allowing you to offer both options simultaneously so visitors can choose what works best for them.

🔧Integration Complexity

  • • Frontend: Add single script tag (2 minutes)
  • • Backend: Implement callback handler (15-30 minutes)
  • • No database changes required (unless linking accounts)
  • • No email service configuration needed

Note: Your dashboard includes an integration toggle that can enable or disable authentication across all your domains. If authentication isn't working, check that the "Integration Status" toggle in your dashboard's "My Integration Code" tab is set to ON (green/active).

🌍Network Requirements

  • • Requires internet connection
  • • Depends on Lightning Network availability
  • • HTTPS required for production (security best practice)
  • • CORS handled automatically by Key-Rex—no configuration needed

Note: Key-Rex service availability depends on Lightning Network uptime. We don't control the Lightning Network, so if it experiences issues, authentication may be temporarily unavailable. See Support for details.

🧪Testing & Staging

Key-Rex supports test domains for safe testing before going live.

  • Test domains are automatically detected and allowed—no need to add them to your dashboard
  • Automatically allowed: localhost, 127.0.0.1, any subdomain starting with test., staging., dev., testing., development., local., demo., sandbox., qa., or preview.
  • Test domains ending in .test, .local, or .example are also automatically allowed
  • Any IP address (e.g., 192.168.1.1) is automatically allowed for testing
  • Perfect for development and staging environments

💡 Important

Test domains don't need to be added to your dashboard—they work automatically without verification. Production domains must be added to your dashboard and verified via DNS TXT record to prove ownership before authentication works.

Domain format: When adding production domains to your dashboard, use only the hostname (e.g., example.com). Don't include protocols (https://) or paths (/path). Subdomains like www.example.com are treated as separate domains and need to be added and verified separately if you want to support both.

Test your integration safely before deploying to production. All test authentication attempts are tracked separately in your dashboard.

Think Key-Rex Will Work for You?

If you have (or can add) a backend server or serverless function, you're ready to try Key-Rex. Get your integration code and start adding Lightning wallet sign-ins to your website. Remember, it's completely free with no credit card required.

Get Your Integration Code →Learn How It Works