Connect Firebase to Fondoo

What Fondoo can do with it

• Paid-access sync to custom claims (default). When a customer's access changes in Fondoo (a purchase, a cancellation), Fondoo looks up the Firebase user and sets the claims plan and status (for example active or canceled). Existing custom claims on that user are kept; only these two keys change. This uses the Identity Toolkit accounts:lookup and accounts:update calls.
• Paid-access sync to Firestore (alternative). Fondoo writes plan and status as string fields into <collection>/<id> in the (default) database. Other fields in the document are left alone.
• Signup sync (optional). With signupSyncEnabled: true, Fondoo pages through your users with accounts:batchGet (100 per page, one page every 5 minutes). Each new user becomes a signup conversion. Fondoo stores only the Firebase UID and a hashed email.
• Health checks. get_connection_health lists users as a probe and reports firebase:<mode> as ok or error.

Fondoo recomputes access at delivery time, so a late retry cannot overwrite a newer cancellation.

Related operations: connect_backend (owner only), set_plan_sync_mapping and test_plan_sync (scope payments:write; money-risk in live mode, so agents need owner approval), get_plan_sync_status (payments:read) and retry_payment_delivery (owner).

Before you start

• A Firebase project with Authentication enabled. Firebase Auth is free up to 50,000 monthly active users on both plans. Firestore includes 20,000 free writes a day (pricing).
• For claims: your checkouts must carry the Firebase UID as externalUserId (for example create_checkout_link({..., externalUserId: "<uid>"})). Claims cannot be keyed by email.
• Fondoo payments set up for your site. Live mode needs a paid Fondoo workspace plan; otherwise you connect test mode.
• Permission to create service account keys. Organizations created on or after 3 May 2024 block key creation by default (iam.disableServiceAccountKeyCreation). An admin must exempt the project (Google Cloud).

Step by step: get your credentials

Use a dedicated service account with only the roles Fondoo needs.

1. In the Google Cloud console select your Firebase project and open IAM & Admin → Service accounts. Create a service account, for example fondoo-sync.
2. Grant roles (Firebase roles):
   • Firebase Authentication Admin (roles/firebaseauth.admin): needed to read users and update custom claims.
   • Firebase Authentication Viewer (roles/firebaseauth.viewer) is enough if you only want signup sync.
   • Cloud Datastore User (roles/datastore.user): only for the Firestore target. It grants read and write access to Firestore data (Google Cloud).
3. Open the account → Keys tab → Add key → Create new key → JSON → Create. The file downloads once.
4. From the JSON file copy three values:
   • project_id → Fondoo projectId (lowercase letters, digits and hyphens)
   • client_email → clientEmail
   • private_key → privateKey

Shortcut: Firebase console → Settings → Service accounts → Generate new private key gives a key for the default Admin SDK account (Firebase). Firebase's page does not list that account's roles, so a dedicated account is safer.

Fondoo asks Google for the identitytoolkit and datastore OAuth scopes. The IAM roles above decide what actually works.

The private key: keep it exactly as in the JSON file, including the \n sequences, and send it inside a JSON body. JSON turns them into real line breaks. If the line breaks are lost or doubled, token signing fails.

Connect it in Fondoo

a. In the dashboard. Under Connections → Available, Connect Firebase gives a Connect securely link with setup steps. There is no form for the service account. Use REST below.

b. With REST (recommended). connect_backend needs the owner scope and has no secure paste page, so run it yourself with an owner-scoped Fondoo API key. With jq you can read the values straight from the file:

jq '{siteId:"YOUR-SITE-ID",provider:"firebase",mode:"test",signupSyncEnabled:true,
     credential:{projectId:.project_id,clientEmail:.client_email,privateKey:.private_key}}' key.json \
| curl -X POST https://api.getfondoo.com/v1/ops/connect_backend \
    -H "Authorization: Bearer $FONDOO_OWNER_KEY" -H "Content-Type: application/json" -d @-

Leave out mode to use your workspace default (live on a paid plan, test otherwise). Repeat with "mode":"live". One backend per site per mode; a new call replaces the old one. Delete key.json when you are done.

c. By asking your agent. Agents without the owner scope get "Owner scope required", and you should not paste a private key into chat. Ask for the rest: "Switch my Firebase plan sync to Firestore collection entitlements keyed by user ID."

set_plan_sync_mapping({siteId, mapping: {target: "firestore", table: "entitlements",
  identity: "externalUserId", keyColumn: "id", planColumn: "plan", statusColumn: "status"}})

For Firebase, target is claims or firestore, never table. table is the collection name. planColumn and statusColumn are the claim or field names. The three column names must differ.

Optional: set_provider({siteId, capability: "backend", provider: "firebase"}) (owner). If set, it must match the connected backend.

Test that it works

1. get_plan_sync_status({siteId, mode: "test"}) shows connected: true, provider: "firebase" and the mapping.
2. Make a test purchase with externalUserId, or run test_plan_sync({siteId, mode: "test", externalUserId: "<uid>"}) for an existing customer.
3. Check the user's custom claims (or the Firestore document). In your app, claims appear in the next ID token: after sign-in, token refresh or getIdToken(true) (Firebase).
4. With signup sync on, get_connection_health({siteId}) should show firebase:test as ok.

Troubleshooting

• "Firebase requires a service account": projectId, clientEmail and privateKey are all required.
• Deliveries fail, then dead_letter: often the key's line breaks, a missing role, or no Firebase user with that UID ("Firebase user missing"). After 5 failed attempts Fondoo raises an alert. Fix it, then retry_payment_delivery.
• "Mapping does not match backend": you chose target: "table", or claims with identity: "email".
• Health error / "Signup sync failed": the account lacks permission to list users. Add a Firebase Authentication role.
• Claims missing in the app: force a token refresh. Keep all claims under 1,000 bytes (Firebase).
• "Live payments require a paid workspace plan": use "mode":"test" or upgrade.

Limits, data and security

• Identity Toolkit allows 21,000 account downloads per minute per project (limits). Fondoo uses far less: one page of 100 users per 5 minutes, on servers with CONNECT_JOBS_ENABLED=true.
• The first signup pass counts existing users at sync time, without backdating. Changing the project or provider clears the list of users already seen.
• Fondoo encrypts the service account with AES-256-GCM, bound to the site, mode and provider. No operation returns it.
• To rotate, create a new key, run connect_backend again, then delete the old key on the service account's Keys tab.
• There is no disconnect operation for backends. To stop access, delete the key or disable the service account in Google Cloud. To stop only signup sync, call connect_backend again with signupSyncEnabled: false.
• No webhooks are used.

Official links

• Add the Firebase Admin SDK
• Firebase predefined roles
• Custom claims
• Authentication limits
• Firestore IAM roles
• Create and delete service account keys
• Firebase pricing