Documentation

Quick Start Guide

This guide will walk you through integrating Universal Verify into your application. We'll cover account setup, SDK installation, and implementing the OAuth flow.

1. Account Setup

Create an Integration

  1. Create an account on Universal Verify
  2. Navigate to your dashboard and create a new integration for your app
  3. Select the scopes you need from your users:
    • Basic scopes (all plans): verification, openid
    • Paid plans: age
    • Enterprise plans: legal_name, date_of_birth, id_type
  4. Add your redirect URL(s) for the OAuth flow
  5. Save your API key and API secret securely (the secret is only shown once)

2. Install SDKs

Frontend SDK

Install via npm:

npm install universal-verify-js

Or use via CDN:

import FrontendSDK from 'https://cdn.jsdelivr.net/npm/universal-verify-js@0.0.2/build/universal-verify.min.js';

Backend SDK

Install via npm:

npm install universal-verify

3. Implement OAuth Flow

Initialize SDKs

// Frontend
const frontendSDK = new FrontendSDK(apiKey);

// Backend
const backendSDK = new BackendSDK(apiKey, apiSecret);

Backend: Generate PKCE Challenge

const { codeChallenge, codeVerifier } = await backendSDK.createCodeChallenge();
// Send codeChallenge to frontend

Frontend: Redirect User

const authUrl = frontendSDK.createAuthorizationUrl({
    codeChallenge: codeChallenge,
    redirectUrl: 'https://your-app.com/callback',
    scope: 'verification openid age', // Optional
    state: 'your-state', // Optional
    nonce: 'your-nonce' // Optional
});

window.location.href = authUrl;

Frontend: Parse Redirect

const { code, state } = frontendSDK.parseRedirectUrl();
// Send code to backend

Backend: Exchange Code for Tokens

const { 
    access_token, 
    refresh_token, 
    id_token, 
    expires_in, 
    scope, 
    sub, 
    token_type 
} = await backendSDK.exchangeCodeForTokens({
    code: code,
    codeVerifier: codeVerifier,
    redirectUrl: 'https://your-app.com/callback'
});

Backend: Get User Info

const userInfo = await backendSDK.getUserInfo(access_token);
// userInfo contains: sub, verified, verification_confidence, age (if requested)

// For sensitive scopes, get additional regional info
if (userInfo.regional_info) {
    const regionalUserInfo = await backendSDK.getRegionalUserInfo(
        access_token, 
        userInfo.regional_info.additional_userinfo_url
    );
}

Backend: Validate ID Token

const tokenClaims = await backendSDK.validateIdToken(id_token, nonce);

Backend: Refresh Tokens (when needed)

const { access_token, refresh_token } = await backendSDK.refreshToken(refresh_token);

Next Steps