Let customers approve website access with their wallet. Build a QR sign-in flow, verify the response on your backend and connect the verified wallet key to your own account system.
This guide describes the current reference implementation. Confirm supported mobile app versions and the approved signing format with Coinductor before launch. Authentication establishes control of a signing key; it does not verify legal identity or authorize a payment.
Use the verified wallet key as an account identifier, offer wallet-based registration, or link a wallet to an existing account. Your service decides which of these actions is allowed.
Your backend issues a random, single-use nonce. The reference lifetime is five minutes.
The browser generates an ephemeral encryption key pair, obtains a relay session ID and combines these with the nonce and website hostname.
The customer scans the QR in Coinductor, reviews the requesting website and confirms access in the wallet.
The wallet sends an encrypted response through the relay. The browser decrypts it and sends the public key, signature and nonce to your backend for verification.
After verification, your backend applies account rules and creates a real authenticated session. Account linking should also require authorization from the existing account.
This is an authentication flow. It does not request a token transfer or demonstrate Connected Checkout.
The example includes an Express backend, a browser QR interface, bundled browser libraries and a command-line wallet simulator.
wss://wss.coinductor.io.
After cloning the repository supplied with your access, run these commands inside its folder:
npm ci
npm start
Open http://localhost:3000 on your computer. A QR code
appears after the browser connects to the relay and obtains a
challenge.
Copy the supplied environment example to your local configuration. For a staging domain, set the allowed origin to that exact HTTPS origin:
PORT=3000
ALLOWED_ORIGINS=https://auth.example.com
NONCE_TTL_MS=300000
auth.example.com is an example, not a Coinductor
service. The current demo also allows local development origins;
configuring this value alone does not harden it for production.
server.jspublic/app.jspublic/index.html and public/style.css
public/vendor/test-simulate-mobile.jsThe hosted relay transports messages between the browser session and mobile wallet. Your own backend remains responsible for authenticating the response.
{sessionId}:{webPublicKey}:{nonce}:{domainName}sessionIdwebPublicKeynoncedomainNameshop.example.com. The
reference maps localhost and local IP development hosts to
localhost.
Show the expiry to the customer and obtain a new challenge when it expires. The backend’s expiry check is authoritative. In a production implementation, bind each challenge to its intended login attempt and invalidate replaced challenges.
Connect the browser to wss://wss.coinductor.io, then
request a session. The reference sends a keep-alive ping every 25
seconds while connected.
{ "action": "getSession" }
{ "action": "ping" }
The session response provides data.sessionId and the
connection origin:
{
"action": "getSession",
"data": {
"sessionId": "<relay-session-id>",
"origin": "https://shop.example.com"
}
}The mobile side sends the encrypted envelope to that session:
{
"action": "sendTo",
"to": "<relay-session-id>",
"domainName": "shop.example.com",
"message": "<JSON-encoded encrypted envelope>"
}
The browser receives action: "clientMessage" and reads
the envelope from data.message. Connection loss must
return the UI to a retry state. Confirm relay error envelopes with
the supported release; the reference client handles
sendToError, while the README also shows an error
attached to sendTo.
The documented JSON envelope contains three Base64 fields:
ephemeralPublicKeyivencryptedData
The reference uses nacl.box.before to obtain a
precomputed key, derives the SecretBox key with SHA3-256, and
decrypts the envelope. Use the supplied implementation and
compatible library versions; raw X25519 output is not a drop-in
replacement for nacl.box.before.
sharedKey = nacl.box.before(mobilePublicKey, browserSecretKey)
finalKey = SHA3_256(SHA3_256(sharedKey) || SHA3_256(emptyBytes))
plaintext = nacl.secretbox.open(ciphertext, iv, finalKey)
This is an algorithm outline: || means byte-array
concatenation. Reject decryption failure. The decrypted object
supplies publicKey, signature and
nonce; optional address fields are not independently
verified by the example backend.
The simulator signs the UTF-8 message below, hashed with SHA3-256, using secp256k1 with low-S signatures:
{domainName}:{publicKey}:{nonce}The public key is compressed hex (33 bytes / 66 characters). The simulator emits a compact signature, while the README includes a DER-shaped example. Confirm encoding and one canonical domain-bound signing format with the mobile team. The demo accepts additional legacy formats, including one without a domain; do not carry that fallback into a production verifier.
These routes belong to the reference application running on your backend. They are not public Coinductor REST endpoints.
GET /api/nonceReturns a new challenge and its expiry. The sample stores challenges in memory.
{
"nonce": "<single-use-uuid>",
"expiresIn": 300,
"expiresAt": 0
}
expiresAt is a Unix timestamp in milliseconds; the zero
above is a placeholder. Use the actual server response.
POST /api/auth/verifySend the decrypted fields as JSON to your backend:
{
"publicKey": "<compressed-public-key-hex>",
"signature": "<signature-hex>",
"nonce": "<issued-challenge>"
}
The reference checks the allowed origin, consumes the challenge,
checks expiry and verifies the signature. A successful response
contains success, token and
user.publicKey. Its random token is a demonstration
value; implement session storage or signed tokens, expiry and logout
before using it for account access.
400 BAD_REQUEST400 INVALID_PUBLIC_KEY403 FORBIDDEN_ORIGIN422 NONCE_EXPIRED_OR_USED422 NONCE_EXPIRED401 INVALID_SIGNATUREThe reference consumes a recognized challenge before signature verification. A failed signature therefore requires a fresh challenge too.
node test-simulate-mobile.js "<COPIED_QR_STRING>"The simulator generates a test key. It does not require your recovery phrase and does not send a blockchain transaction. It uses the hosted relay, so network access is required.
Also test rejection, expiry, reconnecting, repeated submissions and wrong-domain requests. Test account linking and logout in your own application; the demo’s logout only reloads its page.
Review these items with your team and Coinductor before enabling real customer access.
The reference demonstrates protocol mechanics. Its compatibility fallbacks, in-memory nonce store and demonstration session token need production review. Keep payment requests and blockchain confirmation handling separate from authentication.
Request developer access with your website domain, intended sign-in flow and technical contact. The team can share the private reference repository and confirm the supported app builds.