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-credibleStore 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#
| Decision | Suggested action |
|---|---|
| APPROVE | Continue as normal |
| REVIEW | Continue, but ask for email or phone verification before granting free credits |
| DENY | Return a neutral error. Don't say which check fired |
Errors and limits#
| Situation | What to do |
|---|---|
| Timeout, network error or 5xx | The SDK retries, then throws. Fail open and log it |
429 rate limit or daily quota | The SDK retries with backoff, then throws. Fail open, and upgrade if it happens every day |
402 with code trial_ended or subscription_ended | Your account has no active plan. Fail open and choose a plan in the dashboard |
401 or 403 | The 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.