Developer Documentation & Quickstart

Quickstart · ~5 minutes

Integrate passwordless authorization in three steps.

Your server issues a challenge nonce, the wallet signs it, and your server verifies the signature locally. Choose your backend language to view code samples.

1. Step 1

   Install a library

   Verification needs no DigiByte node and no network calls.

   Node.js PHP Browser

   Copy

   npm install digiid express

   Copy

   # PHP 7.4+ with the GMP extension
   git clone --recursive https://github.com/DigiByte-Core/digiid-php
   php -m | grep -i gmp

   Copy

   npm install qrcode   # render the challenge as a QR code

2. Step 2

   Issue a challenge

   Create a random nonce, remember it for ~90 seconds, and show the digiid:// URI as a QR code and a link.

   Node.js PHP Browser

   Copy

   // server.js — issue a challenge (Express)
   import crypto from 'node:crypto';
   import express from 'express';
   import DigiID from 'digiid';
   
   const CALLBACK = 'www.example.com/digiid/callback'; // host + path, no scheme
   const pending = new Map(); // nonce -> { sessionId, expires, address }
   
   const app = express();
   
   app.post('/digiid/challenge', (req, res) => {
     const nonce = crypto.randomBytes(16).toString('hex');
     pending.set(nonce, { sessionId: req.sessionID, expires: Date.now() + 90_000 });
     const { uri } = new DigiID({ nonce, callback: CALLBACK });
     res.json({ uri, nonce }); // digiid://www.example.com/digiid/callback?x=…
   });

   Copy

   <?php
   // login.php — issue a challenge (digiid-php)
   require_once __DIR__ . '/DigiID.php';
   session_start();
   
   $digiid = new DigiID();
   $nonce  = $digiid->generateNonce();          // 32 hex chars from a CSPRNG
   
   // Bind the nonce to this session with a short expiry (see "Nonces & replay").
   $db->prepare('INSERT INTO digiid_nonces (nonce, session_id, expires_at) VALUES (?, ?, ?)')
      ->execute([$nonce, session_id(), time() + 90]);
   
   $uri = $digiid->buildURI('https://www.example.com/digiid/callback.php', $nonce);
   // Render $uri as a link and as a QR code (e.g. with endroid/qr-code).

   Copy

   // login.js — show the challenge in the browser
   import QRCode from 'qrcode';
   
   const { uri, nonce } = await fetch('/digiid/challenge', { method: 'POST' }).then((r) => r.json());
   
   // Tappable on mobile (opens the wallet), scannable on desktop.
   document.querySelector('#digiid-link').href = uri;
   await QRCode.toCanvas(document.querySelector('#digiid-qr'), uri, { width: 240 });
   
   // Wait for the wallet to call back, then continue the session.
   const poll = setInterval(async () => {
     const { state } = await fetch(`/digiid/status?nonce=${nonce}`).then((r) => r.json());
     if (state === 'verified') {
       clearInterval(poll);
       location.assign('/account');
     }
   }, 2000);

3. Step 3

   Verify the callback

   The wallet POSTs address, uri and signature. Check the URI, the nonce and the signature, then consume the nonce.

   Node.js PHP Browser

   Copy

   // server.js — verify the wallet callback (Express)
   app.post('/digiid/callback', express.json(), express.urlencoded({ extended: false }), (req, res) => {
     const { address, uri, signature } = req.body;
     if (!address || !uri || !signature) return res.status(400).json({ error: 'missing fields' });
   
     const digiid = new DigiID({ address, uri, signature, callback: CALLBACK });
     const challenge = pending.get(digiid.nonce);
   
     if (!digiid.uriValid() || !challenge || challenge.expires < Date.now()) {
       return res.status(410).json({ error: 'unknown or expired challenge' });
     }
     if (!digiid.signatureValid()) return res.status(401).json({ error: 'invalid signature' });
   
     pending.delete(digiid.nonce);            // single use: a replay now fails
     sessions.login(challenge.sessionId, address); // address = the user's ID for your site
     res.json({ message: 'Digi-ID verified' });
   });

   Copy

   <?php
   // callback.php — verify the wallet callback (digiid-php)
   require_once __DIR__ . '/DigiID.php';
   $digiid = new DigiID();
   
   // Wallets send JSON; manual signing tools send form fields.
   $input = json_decode(file_get_contents('php://input'), true) ?? $_POST;
   $address   = (string) ($input['address'] ?? '');
   $signature = (string) ($input['signature'] ?? '');
   $uri       = (string) ($input['uri'] ?? '');
   
   $nonce = $digiid->extractNonce($uri);
   $row = $db->prepare('SELECT session_id FROM digiid_nonces WHERE nonce = ? AND expires_at > ? AND address IS NULL');
   $row->execute([$nonce, time()]);
   $challenge = $row->fetch();
   
   $expectedUri = $digiid->buildURI('https://www.example.com/digiid/callback.php', $nonce);
   
   if (!$challenge || $uri !== $expectedUri
       || !$digiid->isMessageSignatureValidSafe($address, $signature, $uri)) {
       http_response_code(401);
       exit(json_encode(['error' => 'invalid or expired Digi-ID challenge']));
   }
   
   // Consume the nonce and attach the verified address to the waiting session.
   $db->prepare('UPDATE digiid_nonces SET address = ? WHERE nonce = ?')->execute([$address, $nonce]);
   echo json_encode(['message' => 'Digi-ID verified']);

   Copy

   // Verify in the browser or any JS runtime with digiid-core (packages/digiid-core in the digi-id.io repo)
   import { verifyCallback } from './digiid-core/src/index.ts';
   
   const result = verifyCallback(
     { address, uri, signature },                          // POST body from the wallet
     { callback: 'https://www.example.com/digiid/callback' }
   );
   
   if (result.valid) {
     // result.nonce -> look up and consume the pending challenge
     // result.address -> the user's Digi-ID for your site
   } else {
     console.warn('Rejected:', result.reason); // bad_request | uri_mismatch | unsecure | bad_signature
   }

Guides

Implementation Guides

Architectural details for session security, key management, and edge cases.

• 15 min

  Add Digi-ID login to a web app

  Challenge, QR code, wallet callback and session hand-off in a small Express app.

  Read guide
• 10 min

  Nonces & Replay Prevention

  How to store, time-box (60–90 seconds), and consume nonces to eliminate replay attacks.

  Read guide
• 15 min

  Cross-Device Polling vs. WebSockets

  Comparing short-polling HTTP endpoints against WebSocket connections for real-time QR authorization updates.

  Read guide
• 10 min

  Add Digi-ID to WordPress

  Install and configure the WordPress plugin, then let users link their wallets.

  Read guide
• 20 min

  Account Binding & Recovery

  Strategies for linking public wallet addresses to existing user databases and handling secondary device pairing.

  Read guide
• 45 min

  Build a door-access prototype

  A kiosk screen per door, one stable callback and an allow-list of Digi-ID addresses.

  Read guide
• 60 min

  Support Digi-ID in your wallet

  Parse digiid:// URIs, derive per-site keys and post signed callbacks.

  Read guide

Brand & UI kit

Make it recognisable.

A consistent “Sign in with Digi-ID” button and QR presentation help users trust the flow.

Sign-in button

• Light SVG
• Dark SVG

QR code guidance

• Label it “Sign in with Digi-ID” above the code.
• At least 200 px, dark modules on a light background, quiet zone intact.
• Also render the URI as a tappable link for mobile users.
• Show a countdown and regenerate after expiry.

Logo

• Logo (light bg)
• Logo (dark bg)