@identistride/verify

@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

• Sign up at identistride.com
• Get 10 free verifications to test
• 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:

• Show a consent dialog to the user
• Call your backend with the consent result
• Guide the user through ID upload and liveness check
• 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

• Never expose API keys in frontend code

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

• Validate user authentication

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

• Handle errors gracefully

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

💬 Support

• Documentation: docs.identistride.com
• Email: [e-mail]
• 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