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_KEY2. 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:screenSignupIf 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#
| Decision | In the function | In your app |
|---|---|---|
| APPROVE | Return nothing | Nothing extra |
| REVIEW | Return a custom claim, such as signupReview: true | Read the claim from the ID token, and grant free credits only after an email or phone check |
| DENY | Throw 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#
| Situation | What to do |
|---|---|
| Timeout, network error or 5xx | Return without blocking (fail open) and log it |
429 rate limit or daily quota | Fail open. Upgrade if it happens every day |
402 with code trial_ended or subscription_ended | Your isCredible 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 |
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.