Integrations

Clerk

Check new Clerk users right after signup, on their first request or from the user.created webhook, and ban or limit risky accounts.

Clerk handles the signup form and creates the user itself. It doesn't offer a hook that lets your own code approve or reject a signup before the user is created, so isCredible checks a new Clerk user right after creation. You then act on the decision: ban or delete the user, or hold back what they can use.

Clerk's own sign-up settings (restrictions, blocklists, bot protection) do apply before an account exists. Keep them on; isCredible works alongside them.

Choose where to check#

WhereData you haveBest for
Your app, on the user's first request after signupEmail, IP address, user agent, device IDMost apps. Gives the sharpest decisions
The user.created webhookEmail and phone, no documented IP addressCatching throwaway and look-alike emails, even if the user never comes back

You can use both. The examples below use Next.js; any backend works the same way with @clerk/backend.

Option 1: check on the first request#

Run the check once, at the first page or API call a new user makes (an onboarding route works well), and store the decision in the user's metadata so it only runs once.

"use server";
import { auth, clerkClient } from "@clerk/nextjs/server";
import { headers } from "next/headers";
import { IsCredibleClient, decide } from "is-credible";

const iscredible = new IsCredibleClient({ apiKey: process.env.ISCREDIBLE_API_KEY!, timeoutMs: 3000, maxRetries: 1 });

export async function screenNewUser(deviceId?: string) {
  const { userId } = await auth();
  if (!userId) return;
  const client = await clerkClient();
  const user = await client.users.getUser(userId);
  if (user.publicMetadata.signupCheck) return; // already checked

  const h = await headers();
  let action: "APPROVE" | "REVIEW" | "DENY" = "APPROVE";
  try {
    const result = await iscredible.verify({
      userId,
      email: user.primaryEmailAddress?.emailAddress,
      ip: h.get("x-forwarded-for")?.split(",")[0]?.trim(),
      userAgent: h.get("user-agent") ?? undefined,
      deviceId,
      accountCreation: true
    });
    action = decide(result).action;
  } catch (err) {
    console.warn("isCredible unavailable, allowing user", err); // fail open
  }

  if (action === "DENY") {
    await client.users.banUser(userId); // signs the user out and stops new sign-ins
    return;
  }
  await client.users.updateUserMetadata(userId, { publicMetadata: { signupCheck: action } });
}

Then gate valuable features on publicMetadata.signupCheck: for example, grant free credits only when it is APPROVE, or after a phone check when it is REVIEW.

Option 2: the user.created webhook#

Clerk sends webhooks after the user is created, and retries any delivery that doesn't get a 2xx response.

  1. In the Clerk dashboard, add a webhook endpoint for your app (for example https://your-app.com/api/webhooks/clerk) and subscribe it to user.created.
  2. Copy the signing secret into CLERK_WEBHOOK_SIGNING_SECRET.
import { verifyWebhook } from "@clerk/nextjs/webhooks";
import { clerkClient } from "@clerk/nextjs/server";
import type { NextRequest } from "next/server";
import { IsCredibleClient, decide } from "is-credible";

const iscredible = new IsCredibleClient({ apiKey: process.env.ISCREDIBLE_API_KEY!, timeoutMs: 3000, maxRetries: 1 });

export async function POST(req: NextRequest) {
  let evt;
  try {
    evt = await verifyWebhook(req);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  if (evt.type === "user.created") {
    const u = evt.data;
    const email = u.email_addresses.find(e => e.id === u.primary_email_address_id)?.email_address;
    const phone = u.phone_numbers.find(p => p.id === u.primary_phone_number_id)?.phone_number;
    try {
      const result = await iscredible.verify({ userId: u.id, email, phone, eventType: "signup", accountCreation: true });
      const { action } = decide(result);
      const client = await clerkClient();
      if (action === "DENY") await client.users.banUser(u.id);
      else await client.users.updateUserMetadata(u.id, { publicMetadata: { signupCheck: action } });
    } catch (err) {
      console.warn("isCredible check failed, allowing user", err); // fail open
    }
  }
  return new Response("ok"); // always 2xx, so Clerk doesn't retry a decision you already made
}

Make the webhook route public in your Clerk middleware, since Clerk calls it without a session.

Acting on the decision#

DecisionSuggested action
APPROVENothing extra
REVIEWKeep the account, but hold back free credits or API keys until a phone or email check
DENYbanUser signs the user out and blocks sign-in. deleteUser removes the account entirely

Banning keeps the account and its email address on record, while deleting frees the address for a new signup. Prefer banning.

Errors and limits#

SituationWhat to do
Timeout, network error or 5xxThe SDK retries, then throws. Leave the user as they are and log it
429 rate limit or daily quotaFail open. Upgrade if it happens every day
402 with code trial_ended or subscription_endedYour isCredible account has no active plan. Fail open and choose a plan in the dashboard
401 or 403The key is wrong, revoked or missing. Fix it; fail open meanwhile