Skip to main content

Getting Started

Launch SafePassage biometric age verification on your site in minutes. This quick start focuses on the JavaScript SDK so you can ship without standing up server infrastructure.

Need Server-Side Control?

This guide covers the JavaScript SDK. For API-based integration with server-side session creation and validation, see the Server Integration Guide.

Prerequisites​

  • SafePassage account (sign up)
  • Access to the SafePassage Dashboard to copy keys
  • A web page where you will launch verification (camera access required)

Frontend Quick Start (SDK)​

Step 1 — Copy your publishable key​

  1. Log in to the SafePassage Dashboard
  2. Click API Keys in the sidebar
  3. Copy your publishable key (pk_…)

Step 2 — Install the SDK​

Option A: CDN

<script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/safepassage.min.js"></script>

Option B: npm

npm install @safepassage/sdk

Step 3 — Launch verification​

Local Server Required

You must serve this page from a web server (http://localhost:...). Opening the HTML file directly (file://) won't work because the verification redirect cannot return to local files. Use any of these:

  • npx serve .
  • python3 -m http.server 8000
  • Your framework's dev server (npm run dev)
<!DOCTYPE html>
<html>
  <head>
    <title>Age Verification</title>
    <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/safepassage.min.js"></script>
  </head>
  <body>
    <h1>Age Restricted Content</h1>
    <button id="verify-btn">Verify Your Age</button>

    <script>
      // Check if running from a local file (won't work - need a server)
      if (window.location.protocol === 'file:') {
        document.getElementById('verify-btn').disabled = true;
        document.getElementById('verify-btn').textContent = 'Requires local server';
        document.body.insertAdjacentHTML('beforeend',
          '<p style="color: red;">This page must be served from http://localhost. ' +
          'Run: npx serve . or python3 -m http.server 8000</p>');
      } else {
        // Initialize with your publishable key (pk_...)
        const sdk = new SafePassage({
          apiKey: 'pk_your_key_here',
          returnUrl: window.location.origin + window.location.pathname
        });

        document.getElementById('verify-btn').onclick = () => {
          // Creates the verification session and opens the SafePassage flow
          sdk.verify();

          // Optional: tie the session to your own user ID
          // sdk.verify({ externalUserId: currentUserId });
        };
      }

      // Check the status parameter that SafePassage adds on redirect
      const params = new URLSearchParams(window.location.search);
      const status = params.get('status');
      const sessionId = params.get('sessionId');

      if (status === 'verified') {
        // User passed verification - show success UI
        document.body.insertAdjacentHTML('beforeend', '<p>Age verified!</p>');

        // IMPORTANT: For production, validate sessionId server-side
        // Client-side status can be forged. See Server Integration Guide.
        console.log('Session ID for server validation:', sessionId);
      } else if (status === 'failed') {
        document.body.insertAdjacentHTML('beforeend', '<p>Verification failed.</p>');
      }
    </script>
  </body>
</html>

Step 4 — Understand the user flow​

  1. The SDK creates a session with your publishable key
  2. The user grants camera access and captures a selfie
  3. Depending on your verification mode, an ID scan may be requested
  4. SafePassage redirects back to your returnUrl with status, and sessionId

What's Next?​

ResourceDescription
JavaScript SDKFull SDK reference with all options
Server IntegrationAPI-based integration with validation
Sessions APIAPI endpoint reference
Verification ModesL1 vs L2 comparison
Code ExamplesAsk support for ready-to-run examples

Need Help?​

  • Email: support@safepassageapp.com