@identistride/verify

Identity verification component for React/Next.js applications with built-in consent management.

💰 Pricing

This is a commercial service. You need an API key to use this package.

👉 Get Started

✨ Features

• 📸 Document upload (driver's license, passport)
• 🤳 Face liveness detection
• ✅ Automated verification
• 🔒 Built-in consent management (compliance-ready)
• 🎨 Customizable UI
• 📦 Zero configuration required

📦 Installation

npm install @identistride/verify

⚠️ Important: This package requires a paid API key. Sign up here.

🚀 Quick Start

1. Get Your API Key

1. Sign up at identistride.com
2. Get 10 free verifications to test
3. Grab your API key from the dashboard

2. Create Backend API Route

The SDK requires a backend endpoint to create verification sessions securely.

Next.js App Router Example

// app/api/verify/create-session/route.ts
import { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  const { consent } = await request.json();

  // Get user ID from your auth system
  const userId = "user_123"; // Replace with actual user ID

  try {
    const response = await fetch(
      "https://api.identistride.com/v1/verify/session",
      {
        method: "POST",
        headers: {
          "X-Api-Key": process.env.IDENTISTRIDE_SECRET_KEY!,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          externalId: userId,
          consent, // Required: true or false
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      return Response.json(error, { status: response.status });
    }

    const session = await response.json();
    return Response.json(session);
  } catch (error) {
    return Response.json({ error: "Session creation failed" }, { status: 500 });
  }
}

Next.js Pages Router Example

// pages/api/verify/create-session.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  const { consent } = req.body;
  const userId = "user_123"; // Get from your auth system

  try {
    const response = await fetch(
      "https://api.identistride.com/v1/verify/session",
      {
        method: "POST",
        headers: {
          "X-Api-Key": process.env.IDENTISTRIDE_SECRET_KEY!,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          externalId: userId,
          consent,
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      return res.status(response.status).json(error);
    }

    const session = await response.json();
    return res.json(session);
  } catch (error) {
    return res.status(500).json({ error: "Session creation failed" });
  }
}

Express.js Example

// routes/verify.ts
import express from "express";

const router = express.Router();

router.post("/create-session", async (req, res) => {
  const { consent } = req.body;
  const userId = req.user.id; // Get from your auth middleware

  try {
    const response = await fetch(
      "https://api.identistride.com/v1/verify/session",
      {
        method: "POST",
        headers: {
          "X-Api-Key": process.env.IDENTISTRIDE_SECRET_KEY!,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          externalId: userId,
          consent,
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      return res.status(response.status).json(error);
    }

    const session = await response.json();
    return res.json(session);
  } catch (error) {
    return res.status(500).json({ error: "Session creation failed" });
  }
});

export default router;

3. Use the Component

The SDK handles consent UI and the entire verification flow automatically.

"use client";

import { VerificationFlow } from "@identistride/verify";

export default function VerifyPage() {
  return (
    <div className="container mx-auto p-4">
      <VerificationFlow
        onCreateSession={async (consent) => {
          const response = await fetch("/api/verify/create-session", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ consent }),
          });

          if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message || "Failed to create session");
          }

          return await response.json();
        }}
        onComplete={(result) => {
          console.log("Verification complete!", result);
          // Redirect or show success message
        }}
        onError={(error) => {
          console.error("Verification failed:", error);
          // Show error notification
        }}
      />
    </div>
  );
}

That's it! 🎉 The SDK will:

1. Show a consent dialog to the user
2. Call your backend with the consent result
3. Guide the user through ID upload and liveness check
4. Return the verification result

📖 API Reference

Props

| Prop | Type | Required | Description | | ----------------- | ---------------------------------------------------- | -------- | ----------------------------------------------- | | onCreateSession | (consent: boolean) => Promise<VerificationSession> | ✅ Yes | Callback to create session via your backend | | onComplete | (result: VerificationResult) => void | ✅ Yes | Called when verification completes successfully | | onError | (error: Error) => void | No | Called when an error occurs | | className | string | No | Additional CSS class names |

Types

VerificationSession

interface VerificationSession {
  sessionId: string;
  providerId: string;
  uploadUrls: {
    documentFront: string;
    selfie: string;
  };
  status: string;
  expiresAt?: number; // Unix timestamp in milliseconds
}

VerificationResult

interface VerificationResult {
  providerId: string;
  email: string;
  name: string;
  verificationStatus: "approved" | "rejected" | "pending" | "failed";
  status: string;
  result?: {
    outcome: "approved" | "rejected" | "needs_review";
    documentQuality: number;
    fraudScore: number;
    details?: {
      documentType?: string;
      country?: string;
      firstName?: string;
      lastName?: string;
      dob?: string;
      documentNumber?: string;
      expiryDate?: string;
    };
  };
}

🔄 Migration from V0 to V1

Breaking Changes

1. Session Creation Now Requires Consent

Before (V0):

const [session, setSession] = useState(null);

useEffect(() => {
  fetch("/api/create-session", { method: "POST" })
    .then(res => res.json())
    .then(setSession);
}, []);

<VerificationFlow session={session} />

After (V1):

<VerificationFlow
  onCreateSession={async (consent) => {
    const res = await fetch("/api/create-session", {
      method: "POST",
      body: JSON.stringify({ consent })
    });
    return res.json();
  }}
/>

2. Backend API Changes

Your backend must now include the consent field:

Before (V0):

body: JSON.stringify({
  externalId: "user_123",
});

After (V1):

body: JSON.stringify({
  externalId: "user_123",
  consent: true, // or false
});

3. Session Expiration

• V0: Sessions expired after 7 days
• V1: Sessions expire after 15 minutes

This change is for abuse management and doesn't affect UX (Rekognition API has its own timeout).

🚨 Error Handling

The SDK and backend API can return several error types:

1. Missing Consent Field (400)

When: consent field not provided in backend request

{
  "error": "Missing required field: consent",
  "message": "Must include consent field (true or false)"
}

Action: Ensure your backend sends consent: true or consent: false

2. Consent Required (200)

When: User declines consent (consent: false)

{
  "message": "Consent is required to start verification",
  "consentRequired": true
}

Action: This is logged for audit. SDK shows error message automatically.

3. Session Already in Progress (409)

When: User tries to create a new session while one is active

{
  "error": "Session already in progress",
  "message": "An active verification session exists.",
  "expiresInSeconds": 723
}

Action: Show error to user, suggest completing existing session

4. Rate Limit Exceeded (429)

When: Too many verification attempts

{
  "error": "Too many verification attempts",
  "message": "Please try again later"
}

Action: Show friendly error, suggest trying tomorrow

5. Insufficient Credits (402)

When: Account has no credits left

{
  "error": "Insufficient credits",
  "message": "Please add credits to your account"
}

Action: Direct user to billing page

Comprehensive Error Handling Example

<VerificationFlow
  onCreateSession={async (consent) => {
    try {
      const response = await fetch("/api/verify/create-session", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ consent }),
      });

      // Handle different status codes
      if (response.status === 409) {
        const error = await response.json();
        const minutes = Math.ceil(error.expiresInSeconds / 60);
        throw new Error(
          `A verification is already in progress. Please wait ${minutes} minutes.`
        );
      }

      if (response.status === 429) {
        throw new Error(
          "Too many verification attempts. Please try again tomorrow."
        );
      }

      if (response.status === 402) {
        throw new Error(
          "Insufficient credits. Please add credits to continue."
        );
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || "Failed to create session");
      }

      return await response.json();
    } catch (error) {
      console.error("Session creation error:", error);
      throw error;
    }
  }}
  onComplete={(result) => {
    if (result.result?.outcome === "approved") {
      console.log("✅ Verification approved!");
      // Handle success
    } else if (result.result?.outcome === "rejected") {
      console.log("❌ Verification rejected");
      // Handle rejection
    } else {
      console.log("⏳ Manual review required");
      // Handle pending state
    }
  }}
  onError={(error) => {
    console.error("Verification error:", error);
    // Show user-friendly error notification
    alert(error.message);
  }}
/>

🎨 Styling

The component comes with default Tailwind-based styles. You can customize with the className prop:

<VerificationFlow
  onCreateSession={createSession}
  className="max-w-lg"
  onComplete={handleComplete}
  onError={handleError}
/>

For custom styling, you can override the default classes in your CSS.

🔒 Security & Compliance

Data Collection & Privacy

The SDK shows users exactly what data is collected and why:

• What we collect: Government-issued ID photo, live selfie
• Why we collect it: Verify identity and liveness
• Data retention:
  • During verification: Temporarily stored
  • After verification: All biometric data and PII deleted immediately
  • What we keep: Only verification result (approved/rejected) for audit

Consent Management

• ✅ Built-in consent dialog meets regulatory requirements
• ✅ Consent text is fixed (not customizable) for compliance
• ✅ Both acceptance and decline are logged for audit trail
• ✅ Users can change their mind after declining

Security Best Practices

1. Never expose API keys in frontend code

   • Always call IdentityStride API from your backend
   • Use environment variables for API keys

2. Validate user authentication

   • Ensure user is authenticated before creating session
   • Use session tokens to identify users

3. Handle errors gracefully

   • Don't expose internal error details to users
   • Log errors server-side for debugging

💬 Support

• Documentation: docs.identistride.com
• Email: [email protected]
• Issues: GitHub Issues Coming soon

📄 Legal

• Terms of Service
• Privacy Policy
• SLA (Enterprise only)

📝 License

This software is commercially licensed. See LICENSE.md for details.

Use requires an active IdentityStride subscription.

Made with ❤️ by IdentityStride | Website