# Firebase Auth

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

> 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

```bash
firebase functions:secrets:set ISCREDIBLE_API_KEY
```

## 2. Write the blocking function

functions/src/index.ts:

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

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

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

> **Warning: 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.
