Integrations

Firebase Auth

Check every new Firebase user before it is created, with a beforeUserCreated blocking function.

Firebase Authentication can run your code before it creates a user, with the beforeUserCreated blocking function. Call isCredible there, and a denied signup never becomes a Firebase user.

Blocking functions need Firebase Authentication with Identity Platform. Upgrade on the Authentication settings page of the Firebase console if you haven't yet.

What triggers it#

beforeUserCreated runs for new users signing up with email and password, phone, and identity providers such as Google or Apple. Anonymous and custom-token sign-ins don't trigger blocking functions. Firebase waits up to 7 seconds for your function, so keep the isCredible call short.

1. Store your key as a secret#

firebase functions:secrets:set ISCREDIBLE_API_KEY

2. Write the blocking function#

import { beforeUserCreated, HttpsError } from "firebase-functions/v2/identity";
import { defineSecret } from "firebase-functions/params";
import { IsCredibleClient, decide } from "is-credible";

const ISCREDIBLE_API_KEY = defineSecret("ISCREDIBLE_API_KEY");
let iscredible: IsCredibleClient | undefined;

export const screenSignup = beforeUserCreated({ secrets: [ISCREDIBLE_API_KEY] }, async (event) => {
  iscredible ??= new IsCredibleClient({ apiKey: ISCREDIBLE_API_KEY.value(), timeoutMs: 3000, maxRetries: 0 });

  let action: "APPROVE" | "REVIEW" | "DENY" = "APPROVE";
  try {
    const result = await iscredible.verify({
      email: event.data?.email,
      phone: event.data?.phoneNumber,
      ip: event.ipAddress,
      userAgent: event.userAgent,
      eventType: "signup",
      accountCreation: true
    });
    action = decide(result).action;
  } catch (err) {
    console.warn("isCredible unavailable, allowing signup", err); // fail open
  }

  if (action === "DENY") {
    throw new HttpsError("permission-denied", "We couldn't create your account.");
  }
  if (action === "REVIEW") {
    return { customClaims: { signupReview: true } };
  }
  return;
});

Install the SDK in your functions folder with npm install is-credible, then deploy:

firebase deploy --only functions:screenSignup

If you remove the function later, also unregister it in the Authentication settings of the Firebase console, or new signups will keep trying to reach it.

Acting on the decision#

DecisionIn the functionIn your app
APPROVEReturn nothingNothing extra
REVIEWReturn a custom claim, such as signupReview: trueRead the claim from the ID token, and grant free credits only after an email or phone check
DENYThrow HttpsError("permission-denied", ...)The client SDK receives an error; show a neutral message

To hold a reviewed account entirely until you look at it, return { disabled: true } instead of a claim.

Send a device ID (optional)#

The blocking function only sees what Firebase passes to it, which doesn't include your own device ID. To add one, run a second check from your backend on the user's first request after signup, with userId, deviceId and ip, and act on it there. See Send device signals.

Errors and limits#

SituationWhat to do
Timeout, network error or 5xxReturn without blocking (fail open) 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

Don't let errors escape

Any error your function throws blocks the signup. Keep the try/catch around the isCredible call, so only a real DENY stops it.