# Express and Node.js

URL: https://iscredible.com/docs/integrations/express

> 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

```bash
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

iscredible.ts:

```typescript
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

app.ts:

```typescript
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`:

```typescript
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.

```typescript
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](https://iscredible.com/docs/guides/usage).

## 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.
