How It Works
Here's how visitors sign in to your website using their Lightning wallets
Overview
Key-Rex lets your website visitors sign in using their Lightning wallets—these are Bitcoin wallets that work on the Lightning Network. Instead of asking for passwords or email addresses, visitors prove who they are using cryptographic signatures (the same security technology that protects Bitcoin).
Here's the simple version: When someone wants to sign in, they click the button on your website. Their wallet app asks them to approve the sign-in request. Once they approve, your website receives proof that they are who they claim to be—no password needed, no email verification required.
Key Benefits: No passwords to breach, no email databases to secure, quick authentication, and minimal privacy compliance burden.
Authentication Flow
Visitor Clicks the Sign-In Button
When someone visits your website and wants to sign in, they click the "Sign in with Key-Rex" button. This starts the sign-in process.
Their Wallet App Asks for Approval
The visitor's Lightning wallet app opens and shows them a sign-in request. This request is unique to this specific sign-in attempt and expires after a short time for security.
Visitor Approves the Sign-In
The visitor taps "Approve" or "Sign In" in their wallet app. Their wallet creates a cryptographic signature that proves their identity. This signature is created using their private key, which never leaves their wallet—it stays secure on their device.
Key-Rex Verifies the Signature
Key-Rex checks that the signature is valid using the same cryptographic security that Bitcoin uses (called ECDSA secp256k1). If the signature is valid, Key-Rex creates a unique identifier for this visitor (called an xpub) and delivers it to your frontend code.
Your Website Signs Them In
Your frontend code receives the visitor's unique identifier (xpub) via a callback function. You then send this xpub to your backend server, which can sign them into your website, link this identifier to their existing account if they're a returning visitor, or create a new account if this is their first time. Then you redirect them to the appropriate page on your site.
If you want to go further, you can also allow a single user account to have multiple wallets by storing more than one xpub for that account in your own database (for example, one for their mobile wallet and one for their desktop wallet).
Technical Note: Key-Rex uses LNURL-auth, which is a standard way for Lightning wallets to handle authentication. This means it works with all major Lightning wallet apps, so your visitors can use whichever wallet they prefer.
Authentication Methods: Key-Rex supports three authentication methods: WebLN (browser extension, one-click authentication - this is the desired/preferred method), QR code popup (desktop fallback when WebLN isn't available), and QR code redirect (mobile fallback). Many wallets currently don't support QR code scanning for LNURL-auth, but we expect them to rapidly incorporate this technology over time as the Lightning Network ecosystem matures.
How to Add Key-Rex to Your Website
Step 1: Add the Button to Your Website
After you sign up and get your integration code, you'll copy the integration code and paste it into your website's HTML. The script automatically initializes when the page loads, so the sign-in button will appear automatically.
<script src="https://keyrex.example.com/embed?siteId=YOUR_SITE_ID"></script>Note: The script auto-initializes when the DOM is ready. Including Key-Rex.init() is optional but recommended for explicit control.
Step 2: Set Up Your Frontend to Receive the xpub
You'll need to set up a callback function in your frontend code that receives the visitor's identifier (xpub) when they sign in. This callback is called automatically by Key-Rex when authentication succeeds.
window.Key-Rex.onSuccess = function(xpub) {
// Send xpub to your backend
fetch('/api/auth/callback', {
method: 'POST',
body: JSON.stringify({ xpub: xpub })
});
};The xpub can be delivered via the onSuccess callback, URL parameters (after QR redirect), cookies, or postMessage (from popup). Your frontend code then sends this xpub to your backend server.
Important: You also need a backend server to receive the xpub from your frontend and create a user session. Without this, visitors can click the button, but they won't actually be signed in. See Requirements for more details and examples.
Step 3: Connect to Your User Accounts (Optional)
If you already have user accounts on your website, you can link the visitor's identifier (xpub) to their existing account. New visitors can sign in and you create accounts for them, while existing users can link their Lightning wallet to their current account. This step is optional—you can also just use the identifier directly if you don't need traditional user accounts.
See FAQ for more details, or check the dashboard Documentation tab after signup for complete code examples and implementation guides.
What Lightning Wallets Are
For someone to sign in with Key-Rex, they need a Lightning wallet app on their phone or computer. These are free apps that work with Bitcoin's Lightning Network. Think of them like a digital wallet that can also prove your identity. Here are the most popular options your visitors might use:
Featured Wallets
Coming Soon
Partner wallets will be showcased here
Good to Know: All Lightning wallets are completely free to download and use. Your visitors can use whichever wallet they prefer—Key-Rex works with any wallet that supports the LNURL-auth standard.
Technical Details (For Developers)
If you're technical and want to understand the underlying technology, here are the key details:
Protocol: LNURL-auth
Key-Rex uses LNURL-auth, which is a standardized protocol for Lightning Network authentication. This ensures compatibility with all major Lightning wallets and follows established industry standards.
Cryptography: ECDSA secp256k1
The authentication signatures use ECDSA secp256k1, which is the exact same cryptographic algorithm that secures Bitcoin transactions. This provides strong security guarantees without relying on passwords or centralized authentication systems.
User Identifier: xpub (Extended Public Key)
Each user is uniquely identified by their xpub (extended public key), which is derived from their Lightning wallet's public key. The xpub is deterministic (always the same for a given wallet) and persistent across sessions, making it ideal for user identification and account linking.
No Personal Data Required
The authentication process requires no email addresses, names, phone numbers, or any other personally identifiable information. Users authenticate purely through cryptographic proof of identity, which significantly reduces privacy compliance requirements (GDPR, CCPA, etc.).