From Zero to Hero: Implementing BigShield in Your App

What This Guide Covers

This is the full walkthrough. By the end, you will have a working BigShield integration that validates signups, interprets fraud scores, handles edge cases, receives webhook notifications, and is ready for production traffic. We will cover every step from creating your account to monitoring your first real validations.

If you prefer a quicker conceptual overview first, check out our developer's guide to email validation. This article is the hands-on, code-at-every-step version.

Step 1: Create Your Account

Head to bigshield.app and sign up. You will need a work email (we practice what we preach, so disposable emails will not work here). The free tier gives you 1,000 validations per month, which is plenty for development and testing.

Once you have verified your email, you will land on the dashboard. Take note of the sidebar navigation: Projects, API Keys, Logs, Analytics, and Settings. We will use most of these.

Step 2: Create a Project and Get Your API Key

Projects in BigShield let you separate different applications or environments. Create one for your app:

1. Click "Projects" in the sidebar
2. Click "New Project"
3. Give it a name (e.g., "My App - Production")
4. Select your plan tier

Now generate an API key:

1. Go to "API Keys" under your project
2. Click "Generate Key"
3. Choose "Live" for production or "Test" for development
4. Copy the key immediately. It will not be shown again.

Your key will look like ev_live_abc123... for production or ev_test_abc123... for testing. Store it securely in your environment variables:

# .env.local (development)
BIGSHIELD_API_KEY=ev_test_your_key_here

# Production (set via your hosting provider)
BIGSHIELD_API_KEY=ev_live_your_key_here

Step 3: Install the SDK

Install the BigShield SDK using your preferred package manager:

# npm
npm install @bigshield/sdk

# pnpm
pnpm add @bigshield/sdk

# yarn
yarn add @bigshield/sdk

The SDK ships with TypeScript types included, so you get full autocomplete and type safety out of the box. It works in Node.js 18+, Deno, Bun, and edge runtimes like Vercel Edge Functions and Cloudflare Workers.

Step 4: Your First Validation

Let us start with the simplest possible integration: validating a single email.

import { BigShield } from '@bigshield/sdk';

const bigshield = new BigShield({
  apiKey: process.env.BIGSHIELD_API_KEY!,
});

async function validateEmail(email: string) {
  const result = await bigshield.validate({ email });

  console.log('Score:', result.score);       // 0-100
  console.log('Verdict:', result.verdict);   // 'allow' | 'deny' | 'review'
  console.log('Signals:', result.signals);   // Array of detected signals

  return result;
}

// Try it
validateEmail('someone@gmail.com');

Run this and you should see a response within 200ms. The test API key returns predictable responses for specific test addresses, while real addresses get full signal analysis.

Step 5: Passing Additional Context

The more context you give BigShield, the better the fraud detection. The email alone gets you a solid baseline, but adding IP address, user agent, and other metadata enables behavioral and network signals.

const result = await bigshield.validate({
  email: 'user@example.com',

  // Network context
  ip: '203.0.113.42',
  userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...',

  // Optional: your internal metadata
  metadata: {
    formId: 'signup-v2',
    referrer: 'https://google.com',
    sessionDuration: 45, // seconds on page before signup
  },
});

Here is how to extract this context in common frameworks:

// Next.js App Router
export async function POST(req: NextRequest) {
  const ip = req.headers.get('x-forwarded-for')?.split(',')[0] || req.ip;
  const userAgent = req.headers.get('user-agent') || undefined;
  // ...
}

// Express
app.post('/signup', (req, res) => {
  const ip = req.ip || req.headers['x-forwarded-for'];
  const userAgent = req.headers['user-agent'];
  // ...
});

Step 6: Understanding the Score

BigShield returns a score from 0 to 100, where higher is more trustworthy. Here is how to interpret the ranges and what actions to take at each level:

Score 85-100: High Trust

The email passed most or all signal checks. Auto-approve the signup with no friction. These users should get the smoothest possible onboarding experience.

if (result.score >= 85) {
  // Auto-approve, full access immediately
  await createUser(email, { tier: 'standard', verified: true });
}

Score 50-84: Moderate Trust

Some signals flagged minor concerns. The email is probably legitimate, but there is enough uncertainty to warrant a lightweight verification step.

if (result.score >= 50 && result.score < 85) {
  // Create account but require email confirmation
  await createUser(email, { tier: 'standard', verified: false });
  await sendVerificationEmail(email);
}

Score 30-49: Low Trust

Multiple signals flagged concerns. This could be a legitimate user with unusual characteristics (VPN user, new email) or a sophisticated fraud attempt. Allow the signup but limit access and flag for review.

if (result.score >= 30 && result.score < 50) {
  // Create limited account, flag for manual review
  await createUser(email, { tier: 'restricted', verified: false });
  await sendVerificationEmail(email);
  await addToReviewQueue(email, result.signals);
}

Score 0-29: Very Low Trust

The email is almost certainly fraudulent. Block the signup and log the attempt for threat intelligence.

if (result.score < 30) {
  // Block signup, log for analysis
  await logBlockedAttempt(email, ip, result.signals);
  return { error: 'Unable to create account with this email.' };
}

Step 7: Working With Signals

Beyond the composite score, BigShield returns individual signals that explain why the score is what it is. Each signal has a name, severity, confidence, and score impact.

interface Signal {
  name: string;
  label: string;
  severity: 'low' | 'medium' | 'high';
  confidence: number;    // 0-1
  score_impact: number;  // negative means it lowers the score
}

// Example: Inspect high-severity signals
const redFlags = result.signals
  .filter((s) => s.severity === 'high')
  .map((s) => s.label);

console.log('Red flags:', redFlags);
// ['Disposable email provider', 'Datacenter IP address']

Storing signals alongside user records gives you powerful analytics later. You can identify which signals are most predictive for your specific user base and tune your thresholds accordingly.

Step 8: Setting Up Webhooks

For Tier 2 signals (deeper analysis that runs asynchronously), BigShield sends results via webhooks. Some signals, like checking if an email has been involved in data breaches or analyzing sending reputation, take 1-3 seconds and run in the background after the initial fast response.

Set up your webhook endpoint:

// app/api/webhooks/bigshield/route.ts
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.BIGSHIELD_WEBHOOK_SECRET!;

function verifySignature(payload: string, signature: string): boolean {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

export async function POST(req: NextRequest) {
  const payload = await req.text();
  const signature = req.headers.get('x-bigshield-signature') || '';

  if (!verifySignature(payload, signature)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'validation.updated': {
      // Tier 2 signals have completed
      const { email, score, signals, verdict } = event.data;

      // Update the stored score if it changed significantly
      await updateUserRiskScore(email, score, signals);

      // If the updated score crosses a threshold, take action
      if (score < 30 && verdict === 'deny') {
        await suspendUser(email, 'Automated: low trust score after deep analysis');
      }
      break;
    }

    case 'domain.flagged': {
      // A domain your users signed up with was just added to the blocklist
      const { domain, reason } = event.data;
      await flagUsersWithDomain(domain, reason);
      break;
    }
  }

  return NextResponse.json({ received: true });
}

Register your webhook URL in the BigShield dashboard under Settings > Webhooks. You can choose which event types to receive.

Step 9: Dashboard Monitoring

Once validations start flowing, the BigShield dashboard becomes your fraud command center. Here is what to monitor:

Key Metrics

• Block rate: What percentage of signups are being blocked? If it suddenly spikes, you might be under attack. If it drops to near zero, something might be misconfigured.
• Average score: Track this over time. A declining average suggests increasing fraud pressure.
• Signal frequency: Which signals fire most often? This tells you what kind of fraud you are seeing.
• Response times: BigShield targets sub-200ms. If you see latency increasing, check your network route.

Setting Up Alerts

Configure alerts for anomalous patterns:

• Block rate exceeds 25% in a 1-hour window (possible attack)
• Single IP triggers more than 10 validations in 5 minutes (bot behavior)
• New disposable domain appears more than 50 times in a day (emerging threat)

Step 10: Going to Production

Before switching from test to live, run through this checklist:

Pre-Launch Checklist

• Switch to a live API key. Replace ev_test_ with ev_live_ in your production environment variables.
• Set up error handling. Make sure your integration fails open (allows signups) if BigShield is unreachable.
• Configure rate limits. BigShield has built-in rate limiting, but also add your own application-level limits.
• Test webhook delivery. Use the "Send Test Event" button in the dashboard to verify your webhook endpoint processes events correctly.
• Set score thresholds. Start with the defaults (block below 30, review below 70, allow above 70) and tune from there.
• Enable logging. Log every validation result for debugging and analytics. Include the request ID from the response headers for support requests.

Gradual Rollout

Consider a gradual rollout rather than flipping the switch for all traffic at once:

async function shouldValidate(email: string): Promise<boolean> {
  // Week 1: Validate 10% of signups (shadow mode, log but do not block)
  // Week 2: Validate 50%, start blocking score < 20
  // Week 3: Validate 100%, block score < 30
  const rolloutPercentage = 100; // Adjust as you gain confidence
  const hash = simpleHash(email);
  return (hash % 100) < rolloutPercentage;
}

async function handleSignup(email: string, ip: string) {
  if (await shouldValidate(email)) {
    const result = await bigshield.validate({ email, ip });

    // Shadow mode: log but do not block
    if (SHADOW_MODE) {
      console.log('[BigShield Shadow]', email, result.score, result.verdict);
      return { allowed: true };
    }

    // Active mode: enforce thresholds
    if (result.score < 30) {
      return { allowed: false, reason: 'Low trust score' };
    }
  }

  return { allowed: true };
}

Step 11: Ongoing Optimization

Your integration is live. Now make it better over time.

Track False Positives

When a legitimate user contacts support because they were blocked, log the false positive. Use BigShield's feedback API to report it:

await bigshield.feedback({
  email: 'legitimate-user@example.com',
  validationId: 'val_abc123',
  actual: 'legitimate',
  notes: 'User verified via support ticket #4521',
});

This improves BigShield's models and your future accuracy.

Tune Thresholds

After a few weeks of data, review your block/review/allow distribution. If you are seeing too many false positives, raise the block threshold from 30 to 25. If fraud is still getting through, lower the review threshold from 70 to 60.

Automate With Webhooks

As you learn which Tier 2 signals are most relevant to your fraud patterns, build automated responses. For example, if "breach history" signals are a strong predictor of abuse for your platform, automatically require email verification when that signal fires.

Complete Integration Example

Here is a condensed version of everything above in a single utility module:

// lib/bigshield.ts
import { BigShield } from '@bigshield/sdk';

const client = new BigShield({
  apiKey: process.env.BIGSHIELD_API_KEY!,
  timeout: 5000, // 5 second timeout
});

interface ValidationDecision {
  allowed: boolean;
  requiresReview: boolean;
  requiresVerification: boolean;
  score: number | null;
  signals: string[];
}

export async function validateSignup(
  email: string,
  ip?: string,
  userAgent?: string
): Promise<ValidationDecision> {
  try {
    const result = await client.validate({ email, ip, userAgent });

    return {
      allowed: result.score >= 30,
      requiresReview: result.score >= 30 && result.score < 50,
      requiresVerification: result.score < 85,
      score: result.score,
      signals: result.signals.map((s) => s.label),
    };
  } catch (error) {
    console.error('[BigShield] Validation failed:', error);
    // Fail open
    return {
      allowed: true,
      requiresReview: true, // Flag for review when validation fails
      requiresVerification: true,
      score: null,
      signals: ['validation_unavailable'],
    };
  }
}

What Comes Next

You have gone from zero to a production-ready BigShield integration. Your signup form now validates against 20+ fraud signals, handles edge cases gracefully, receives asynchronous signal updates, and gives you a dashboard to monitor it all.

For more advanced use cases, like plugging BigShield into your LLM pipeline to prevent token abuse, see our guide on hooking BigShield into your LLM pipeline.

Ready to get started? Create your free account at bigshield.app and follow these steps with your own app. The first 1,000 validations are on us.