Add a referral program to your Base44 app
Base44 apps use built-in Base44 authentication and run trusted code in backend functions on Deno. A backend function knows the signed-in user through createClientFromRequest, so it can send the signup with a key from the app's secrets.
What Base44 builds, and where the signup call goes
- Frontend
- React single-page app
- Accounts
- Built-in Base44 authentication
- Server code
- Backend functions (Deno), called with base44.functions.invoke
- Secrets
- App secrets, read by backend functions as environment variables
Signup boundary: A backend function, called once right after the first sign-in, reads the user with base44.auth.me() and sends the signup with the handle that the page passes.
Before you start, create a Project and a referral Program in RefRef, and keep the API key, Project ID, and Program ID ready. The integration reference has each step. Store them as server secrets: App secrets in the dashboard, or base44 secrets set. Setting a secret redeploys the functions.
1. Capture referral clicks
Paste into the Base44 chat first.
Add the RefRef landing script to the <head> of every page where a referral link can land, with the URLs from configuration: <script src="https://assets.refref.ai/attribution.v1.js" data-api-url="https://api.refref.ai" defer></script>. Before the signup form submits, wait for window.RefRefAttribution?.capture() for at most 3 seconds, then continue the signup even if capture fails. Do not create, change, or delete the refref_handle cookie. Do not store referral data in localStorage.2. Send each new account to RefRef
Add REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID as app secrets first.
Connect each new account to the referral click. Create a backend function named refrefSignup. In it, call createClientFromRequest(req) and base44.auth.me() to get the signed-in user; never take the user ID from the request body. Send POST {REFREF_API_URL}/v1/track/events with the X-Api-Key header and { projectId, type: "signup", participant: { kind: "individual", externalId: user.id }, occurredAt: user.created_date, identify: { handle } }, where handle is the refref_handle value that the page sends in the body; leave out identify without one. Send nothing when user.created_date is more than 10 minutes ago. Read REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID from secrets, and REFREF_API_URL with the default https://api.refref.ai. In the app, right after a user signs in for the first time, read the refref_handle cookie and call base44.functions.invoke("refrefSignup", { handle }). A RefRef failure must never block the app.3. Show each user their invite link
Optional.
Add an "Invite friends" card to the account page. In a backend function named refrefInvite that reads the user with base44.auth.me(), for the signed-in user only, call POST https://api.refref.ai/v1/enrollments and then POST https://api.refref.ai/v1/referral-codes, each with { projectId, programId: REFREF_PROGRAM_ID, participant: { kind: "individual", externalId: <user ID> } } and the X-Api-Key header. Show the link https://r.refref.ai/<code> with a Copy button that announces "Copied". Show three states: loading, ready, and "We could not load your invite link" with a Try again button. Never show a placeholder link, a made-up count, or made-up earnings.The backend function that prompt 2 should produce
Compare the generated code with this reference before you publish. The user must come from the verified session, the key from a secret, and a RefRef failure must not block the user.
functions/refrefSignup.ts
import { createClientFromRequest } from "npm:@base44/sdk";
Deno.serve(async (req) => {
const base44 = createClientFromRequest(req);
const user = await base44.auth.me(); // the signed-in user, never the body
if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
// Only a new account sends a signup: the page cannot attribute an old one later.
if (Date.now() - new Date(user.created_date).getTime() > 10 * 60_000)
return Response.json({ sent: false });
const { handle } = await req.json().catch(() => ({}));
const response = await fetch(`${Deno.env.get("REFREF_API_URL") ?? "https://api.refref.ai"}/v1/track/events`, {
method: "POST",
headers: { "Content-Type": "application/json", "X-Api-Key": Deno.env.get("REFREF_API_KEY")! },
body: JSON.stringify({
projectId: Deno.env.get("REFREF_PROJECT_ID"),
type: "signup",
participant: { kind: "individual", externalId: user.id },
occurredAt: user.created_date,
...(typeof handle === "string" && handle && { identify: { handle } }),
}),
});
return Response.json({ sent: response.ok });
});Watch for
- Base44 keeps the session token in localStorage, not a cookie, so only the page can tell the function about the referral handle. Call the function right after the first sign-in.
- The page decides when to call the function, so the function itself refuses accounts older than 10 minutes. RefRef also takes only the first signup of each user, and refuses an account created before the RefRef Project.
- Use asServiceRole only where you need it: it bypasses the app's access rules.
What you get
For the program, start from the Double-sided referral program template. Base44 apps are often community and event apps, where both sides need a reason to act.
your-app.com/account · built with Base44
Event RSVP app
Invite friends
Share your link. You both get a reward when your friend signs up.
RefRef Console · Referrals
- Referrer
- user-a (your user ID)
- Referee
- user-b (your user ID)
- Touch
- click → signup
- Program
- Invite friends
- Reward
- earned, waiting for delivery
What we ran, and what happened
Some checks have not run yet. Treat the open steps as a guide to verify yourself, and record your own results.
- pendingThe prompts produce the integration in Base44
- Not run: it needs a signed-in Base44 account on the Builder plan or higher for secrets and functions, and generation uses builder credits. Paste prompts 1 and 2 into a test app, then compare the generated code with the reference code.
- pendingTwo-user journey on the published app
- Not run. On the published app at its final domain: follow A's link as B, sign up, and check the referral in the Console; sign in again as B and check that no second signup arrives; search the browser bundle for the API key.
- passed · 2026-10-20The request of the reference code matches the RefRef API
- The reference code sends the same signup body (projectId, type, participant, identify) that the rehearsal journey of the coding-agent guides sent to a disposable RefRef stack, where it created the referral. The function itself has not run on the builder.
01Does this give me Base44 credits?
No. It adds a referral program to the app that you build with Base44, so that your users can invite their friends and you can reward them. Credits for inviting people to Base44 itself are a separate offer of Base44.
02Why does the page send the referral handle to the function?
Base44 keeps the session in localStorage, so a backend function sees the user but not the browser's cookies. The page reads the refref_handle cookie and passes it once, right after the first sign-in.
Official references
Start with a Sandbox Project
Create a RefRef account, add a Project, and get the keys that the Base44 prompts need. Sandbox data never mixes with live data.