Integrations

Express and Node.js

Protect signup routes and expensive requests in an Express app with the is-credible SDK.

Add one call to the Express routes that hand out something valuable: signup, trial start, password reset, or an expensive API request.

Install#

npm install is-credible

Store your key as ISCREDIBLE_API_KEY in the server's environment. Node.js 18 or later is required.

A small helper#

import { IsCredibleClient, IsCredibleError, decide, type Recommendation, type UserData } from "is-credible";

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

/** Returns APPROVE, REVIEW or DENY. Returns APPROVE when the check can't run (fail open). */
export async function screen(data: UserData, scenarioId?: string): Promise<Recommendation> {
  try {
    const result = await iscredible.verify(data, scenarioId ? { scenarioId } : {});
    return decide(result).action;
  } catch (err) {
    if (err instanceof IsCredibleError && err.status === 402) {
      console.error("isCredible: no active plan, checks are paused", err.code); // trial_ended or subscription_ended
    } else if (err instanceof IsCredibleError && err.status === 429) {
      console.warn("isCredible: rate limit or daily quota reached");
    } else {
      console.warn("isCredible unavailable, allowing the request", err);
    }
    return "APPROVE";
  }
}

Protect the signup route#

import express from "express";
import { screen } from "./iscredible";

const app = express();
app.set("trust proxy", 1); // behind a load balancer or proxy, so req.ip is the client
app.use(express.json());

app.post("/signup", async (req, res) => {
  const { email, password, deviceId } = req.body;

  const action = await screen({
    email,
    ip: req.ip,
    userAgent: req.get("user-agent"),
    deviceId,
    accountCreation: true
  });

  if (action === "DENY") return res.status(403).json({ error: "We couldn't create your account." });

  const user = await createUser(email, password, { needsVerification: action === "REVIEW" });
  res.json({ id: user.id });
});

Set trust proxy to match your setup. Without it, req.ip is the address of your proxy, not the user. Never send the password to isCredible.

As middleware#

To protect several routes the same way, wrap the check in middleware and keep the decision on res.locals:

import type { RequestHandler } from "express";

export const screenRequest = (scenarioId?: string): RequestHandler => async (req, res, next) => {
  const action = await screen(
    { email: req.body?.email, ip: req.ip, userAgent: req.get("user-agent"), deviceId: req.body?.deviceId },
    scenarioId
  );
  if (action === "DENY") return res.status(403).json({ error: "Request not allowed." });
  res.locals.riskDecision = action; // "APPROVE" or "REVIEW"
  next();
};

app.post("/contact", screenRequest("SYS_SUBMISSION_SCREENING_001"), saveContactForm);

Protect expensive requests#

Check usage before costly work such as AI calls. The SDK caches each answer and only calls the API when a check is due.

const decision = await iscredible.checkUsage(
  req.user.id,
  { metric: "ai_tokens", used: tokensUsedThisMonth, limit: 100000 },
  { deviceId: req.body.deviceId, ip: req.ip }
);
if (decision.action === "DENY") return res.status(429).json({ error: "Free limit reached" });

Wrap it in try/catch and continue on errors, as screen does. See Stop resource abuse.

Acting on the decision#

DecisionSuggested action
APPROVEContinue as normal
REVIEWContinue, but ask for email or phone verification before granting free credits
DENYReturn a neutral error. Don't say which check fired

Errors and limits#

SituationWhat to do
Timeout, network error or 5xxThe SDK retries, then throws. Fail open and log it
429 rate limit or daily quotaThe SDK retries with backoff, then throws. Fail open, and upgrade if it happens every day
402 with code trial_ended or subscription_endedYour 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

verify also throws before any request when the data is invalid, for example a malformed email address. The catch in screen covers that case too.