> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Base44 backend functions: Backend functions (mobile apps)

> source commit is in /SOURCE_COMMIT at the repository root. Edits here are overwritten by

<Warning>
  This page is part of an AI coding agent skill and is written for agents, not humans. For the human-readable Base44 docs, see the [developer documentation](https://docs.base44.com/developers).
</Warning>

# Base44 backend functions: Backend functions (mobile apps)

When a user asks you to integrate with an external API that has no built-in integration, you can write custom backend functions to integrate with the API.
The backend functions are basically an HTTP handler that you can define in `base44/functions/{functionName}/entry.ts`.
It has to export a fetch function that will be called with the incoming request. Logic needed by more than one function must live in a `base44/shared/` module they both import — extract it, never copy it between functions.

The Core-integration routing rule is an exception: use a backend function for Core methods except `UploadPublicFile`, `UploadPrivateFile` and `CreateFileSignedUrl` (`UploadFile` is the retired spelling of `UploadPublicFile`).

For external webhooks, browser GET links and OAuth callbacks, use the server-set `X-Base44-App-Url` origin plus `/functions/<functionName>`. Never expose deployment URLs. Preserve callback query parameters and validate OAuth state in the handler.

\<guest\_checkout>

* Narrow exception to the authentication/service-role rules: public checkout initiation may run without login, including a server-side payment-provider call and creation of a new pending order. A guest checkout is safe only when the server selects the payable products, prices and currency from server configuration, provider-owned prices, or catalog records buyers cannot create, update or delete, validates quantities, returns only the new checkout's details, and neither exposes nor changes existing customer/order/entitlement records chosen by the caller. Reading the public catalog through service role does not invalidate this exception. This does not exempt other anonymous writes, messages, paid AI calls or privileged payment operations.
* Never leave these payment trust-boundary failures in the code: caller-controlled amounts/prices/currency or payment status, access to another customer's records, or fulfillment/pass/access granted before server-side payment-provider verification. A success redirect, a client-supplied session/order id, or the presence of a signature header alone is not proof of payment.
* When hardening a payment flow, preserve intended guest checkout and its successful response shape. Fix pricing, record scoping and payment verification at the relevant boundary; do not require login or a browser-embedded shared secret merely to start checkout.
* Origin/Referer/Host headers are not caller authentication or proof of payment. Do not add an Origin-equals-Host restriction as a security fix: legitimate custom-domain, platform-domain and preview callers may use different API hosts. Preserve platform app/Host binding and legitimate redirect/CORS allowlists; check both custom-domain and platform-domain guest checkout after changes.
  \</guest\_checkout>

\<code\_validation>
**Validation Flow**: After you generate the function code, it automatically goes through lint validation before deployment.

**What gets REJECTED** (deployment fails):

* Syntax errors, missing imports, unmatched brackets/braces
* Wrong function structure or return types

**What PASSES** (deployment succeeds):

* Unused variables, `let` instead of `const`, unused catch parameters
* These "style" issues are ignored to prevent deployment loops

\<mandatory\_requirements>

* must use `export default async function(req) { ... }` handler - no other patterns accepted
* must declare variables before using them (use `const`, `let`, or `var`)
* must not redeclare variables already in scope (e.g. `user`, `req`)
* must prefix **external-dependency** imports with `npm:package@version` (relative imports of your own files are not external deps)
* must return Response objects - never return strings or plain objects directly
* must return 4xx for caller errors before the work, never `throw` them into the catch: 400 bad/missing input (an unparseable body too: `await req.json().catch(() => ({}))`), 401/403 auth, 404 missing record; SDK calls reject instead of returning null (`auth.me()` signed out: 401, `entities.X.get(id)` on a missing id: 404): before the `if (!x)` guard, turn only that status into null (`.catch((e) => (e.status === 404 ? null : Promise.reject(e)))`), or the guard never runs and the catch returns 500; a 429 or outage still rejects; try/catch the rest — the catch's 500 means the function crashed
* must validate user authentication with `base44.auth.me()` when using Base44 SDK
* Exception: use `base44.asServiceRole.integrations.Core` for Core-integration functions. Keep the function narrowly scoped: validate and bound its input, return only the needed result, and do not use the service role for entities or other app data.
* must use proper JavaScript/TypeScript syntax with matched brackets and braces
* must validate all regex patterns are syntactically correct before writing
* must not throw or `await` at module top-level — keep all init inside the handler (top-level failures cause boot errors, not 500s)
* must `await` every Base44 SDK call (`base44.entities.X.list()`, `base44.auth.me()`, `base44.functions.invoke(...)` all return Promises)
* **Shared modules** - never duplicate logic across functions; extract it to a `base44/shared/` module, e.g. `import { calc } from "../../shared/calc.ts"`; own-dir helpers import as `./util.ts`.
* **Never cross the boundary** - `base44/` is server-side and never in the client bundle: never import it from a frontend file (the screen calls `base44.functions.invoke(...)` instead), and never import `src/` or `@/` from a function.
  \</mandatory\_requirements>
  \</code\_validation>

\<guidelines>
\<main\_guidelines>

1. CRITICAL: before writing any function, if you need to use a secret / api key, make sure to check if it's already set. If it is missing, ask the user to add it on the app's Dashboard → Secrets page.
2. ADMIN-ONLY FUNCTIONS: If a function should only be invoked by admin (e.g., scheduled tasks, functions a workflow or automation calls, admin dashboard operations, system maintenance), it MUST verify the authenticated user is an admin by checking `user.role === 'admin'` and return 403 Forbidden if not.
3. **SSO TOKEN SUPPORT**: If the app has an SSO provider configured and the function needs that provider's APIs (Google, Microsoft, etc.), use `await base44.asServiceRole.sso.getAccessToken(user.id)`, or `await base44.asServiceRole.sso.getIdToken(user.id)` if an email claim is required in the token. When a configured SSO provider matches the external API, use its token instead of asking the user for an API key: the access token goes in the `Authorization` header unchanged (it already carries its scheme), the ID token as `Bearer <token>`.

If the secrets you need are not set, ask the user to add them on the app's Dashboard → Secrets page (shown once backend functions are on) and wait for their confirmation before writing the function code.

A function that reads an unset secret or API key fails at runtime.

For example, if the user asks for a WeatherAPI.com integration, you should request the WEATHER\_API\_KEY secret.

**App Connectors Overview**
When a user asks for an integration to an external service, there is a capability called **app connectors** which allows users to connect to specific services using an OAuth flow with requested scopes. The supported connectors are listed by the `list_connectors` MCP tool (or `base44 connectors list-available`); see the `base44-platform-connectors` skill.

**Integration Priority:**
When the user needs to integrate an external service, you MUST prioritize methods in the following order:

1. **App Connectors**: If the integration is supported by app connectors, you MUST prioritize it over all other methods. App connectors provide secure OAuth-based authentication with specific scopes.

2. **Backend Functions with Secrets**: If app connectors are not available, use backend functions with API keys/secrets.

**Important**: Always check if the requested integration is supported by app connectors first. If it is supported, use app connectors exclusively. Only fall back to other methods if the integration is not supported by app connectors.

For example, if the user wants to integrate Google Calendar and it's supported by app connectors, always use the app connector OAuth integration. If app connectors support it but backend functions are not enabled, ask the user to enable them first, then proceed with the app connector authorization flow.
\</main\_guidelines>

\<usage>

THE ONLY WAY TO USE A FUNCTION in a page / component / layout is to use it from the base44 sdk.
the response of the function will be an axios response object.

for example:
import \{ base44 } from "@/api/base44Client";

...
const response = await base44.functions.invoke('someFunction', \{someParam: "someValue"})
...

The response is an Axios response object with structure: `{data, status, headers}` - your function's returned data is in `response.data`.

\</usage>

\<coding\_instructions>

1. Prefer Web-standard APIs over external dependencies (eg: use fetch instead of Axios, use WebSockets API instead of node-ws)

2. Import every external dependency with an `npm:` specifier, e.g. `import Stripe from "npm:stripe@18.5.0"`.

3. Pin a version on every external import. For the Base44 SDK use exactly `npm:@base44/sdk@0.8.54`.

4. Already have an `esm.sh` or `unpkg.com` URL? Replace the CDN hostname with the `npm:` specifier.

5. Export a default request handler: `export default async function(req) { ... }`.

6. Secrets: `import { secrets } from "base44:runtime"` → `secrets.get("NAME")`; pre-populated: BASE44\_APP\_ID. Users manage secrets on the Dashboard "Secrets" page (its own sidebar item, shown once backend functions are on), not in Settings.

7. NEVER ask users for BASE44\_SERVICE\_TOKEN, BASE44\_SERVICE\_ROLE\_KEY, or similar - these secrets don't exist. Use `createClientFromRequest(req)` for auth, and `base44.asServiceRole` for service role level operations.

8. Naming: USE ONLY camelCase for function names. No spaces, no /, no hyphens.
   **REMEMBER**: the frontend calls functions only through `base44.functions.invoke` - see usage above.

9. Use `base44:runtime` for secrets (`secrets.get`) and post-response work (`waitUntil`). For work to complete after sending a response: `import { waitUntil } from "base44:runtime"; waitUntil(myAsyncOp())`.

10. Write files using javascript. No need to use typescript.

11. Don't use multiple paths, only / is allowed when making an API call.

12. Parameters can only be passed through the payload. URL parameters are not allowed and won't work.

13. CRITICAL: For stripe webhooks make sure to do base44 auth after setting the token from request.headers before ANY stripe signature validation.

14. WEB CRYPTO IS ASYNC: The runtime uses the Web Crypto API (SubtleCrypto) which is asynchronous, unlike Node.js's synchronous crypto. For Stripe webhook signature verification, you MUST use `await stripe.webhooks.constructEventAsync(body, signature, secret)` instead of `constructEvent()`. The synchronous version will throw "SubtleCryptoProvider cannot be used in a synchronous context".

15. **SSO TOKEN HANDLING**: When a function needs to access external APIs and the app has an SSO provider configured for that service, use the `base44.asServiceRole.sso.getAccessToken(user.id)` method to get the access token, no need to do anything else.

16. Base44 SDK usage (service role + request-based init):
    16.a Always import the SDK as: `import { createClientFromRequest } from 'npm:@base44/sdk@0.8.54';`
    16.b Create the client from the incoming request:
    \<example>
    import \{ createClientFromRequest } from 'npm:@base44/sdk\@0.8.54';

export default async function(req) \{
try \{
const base44 = createClientFromRequest(req);
const user = await base44.auth.me().catch((e) => (e.status === 401 ? null : Promise.reject(e)));

if (!user) \{
return Response.json(\{ error: 'Unauthorized' }, \{ status: 401 });
}

// User-scoped operations (use app-user token)
const items = await base44.entities.SampleData.list();

// Service-scoped operations (admin privileges)
const allItems = await base44.asServiceRole.entities.SampleData.list();

return Response.json(\{ items, allItems });
} catch (error) \{
return Response.json(\{ error: error.message }, \{ status: 500 });
}
}

\</example>
16.c When to use service role vs user auth:

* Prefer user-scoped calls (`base44.entities/...`) when responding to frontend/user actions.
* Use service role (`base44.asServiceRole`) for Core-integration functions; otherwise only when necessary for admin-level operations and AFTER verifying:
  * For entities, functions, and non-Core integrations, there is an authenticated user (base44.auth.isAuthenticated() is true), and
  * The business logic allows elevating privileges for this action.
* For webhooks or endpoints intended to be called without user authentication:
  * Use the service role to interact with Base44.
  * FIRST validate the request authenticity:
    * If it's a webhook from a known provider, use its official signature validation or npm package.
    * Otherwise, suggest adding a shared secret as a query param when registering the webhook and verify it on each call.
* With `base44.asServiceRole` you can use the following methods:
  * `base44.asServiceRole.entities` - For working with entities as admin.
  * `base44.asServiceRole.functions` - Call backend functions.
  * `base44.asServiceRole.integrations` - Call integrations.
    16.d Calling other backend functions:
* You can invoke another backend function via the SDK:
  \<example>
  const res = await base44.functions.invoke('myFunction', \{ foo: 'bar' });
  \</example>

17. **SHARED CODE**: Never duplicate logic across functions — put it in a `base44/shared/` module and import it (`import { x } from "../../shared/x.ts"`); own-dir helpers import as `./util.ts`.
18. Never load full datasets into memory — paginate entity queries, stream large external responses.
19. **Fast requests**: requests are cut at 5min and a Worker holds 6 connections at once. Run independent calls in `Promise.allSettled` batches of \~6, never one await per item; one `filter({ id: { $in: ids } })` instead of a get per id; every outbound `fetch` takes `signal: AbortSignal.timeout(ms)` sized to the API (\~10s, more for LLM/media); on 429 back off or fail, never a tight retry loop.
20. Do NOT use `eval()` or `new Function()`.
21. Do NOT instantiate WebAssembly from bytes constructed at runtime.
    \</coding\_instructions>

\<admin\_only\_functions\_guideline>
**CRITICAL: Admin-Only Function Authentication**

When creating backend functions that should ONLY be invoked by admin (e.g., scheduled tasks, functions a workflow or automation calls, admin dashboard operations, system maintenance), the function MUST:

1. **Authenticate the user** using `base44.auth.me()`
2. **Verify the user is an admin** by checking `user.role === 'admin'`
3. **Return 403 Forbidden** if the user is not an admin

\<example>
const base44 = createClientFromRequest(req);
const user = await base44.auth.me().catch((e) => (e.status === 401 ? null : Promise.reject(e)));

if (user?.role !== 'admin') \{ return Response.json(\{ error: 'Forbidden: Admin access required' }, \{ status: 403 }); }

// Proceed with admin-only operations...
\</example>

This prevents non-admin users from invoking sensitive operations by directly calling the function endpoint.
\</admin\_only\_functions\_guideline>

\</guidelines>

\<when\_to\_use\_backend\_functions>
Use backend functions only when the user asks you to integrate with an external API that has no built-in integration.
Always prefer to use the built-in integartions, as described in the `base44-platform-integrations-sdk` skill, over using backend functions.

\</when\_to\_use\_backend\_functions>

\<example>

**Request:** Please integrate OpenAI's gpt-4o-mini model to the app, using a backend function.
I want you to tell a joke to the user based on their name.

**Response:**
Before writing such a function, I will need your help to set the OPENAI\_API\_KEY secret.

I need the OPENAI\_API\_KEY secret first — please add it on the app's Dashboard → Secrets page (create one at [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)).

**Request:** I have now set the OPENAI\_API\_KEY secret.
Please write the backend function.

**Response:**
Sure, let me create the function for you.

```
// base44/functions/openai/entry.ts
import { createClientFromRequest } from 'npm:@base44/sdk@0.8.54';
import OpenAI from 'npm:openai';
import { secrets } from 'base44:runtime';

export default async function(req) {
    try {
        const base44 = createClientFromRequest(req);

        const user = await base44.auth.me().catch((e) => (e.status === 401 ? null : Promise.reject(e)));
        if (!user) {
            return Response.json({ error: 'Unauthorized' }, { status: 401 });
        }

        // Construct SDK clients inside the handler — module-level init throws on missing
        // secrets and crashes boot (no try/catch reached, no logs from app code).
        const openai = new OpenAI({ apiKey: secrets.get("OPENAI_API_KEY") });

        const response = await openai.chat.completions.create({
            model: "gpt-4o-mini",
            messages: [
                {
                    role: "system",
                    content: "You are a witty comedian specializing in clean, clever jokes."
                },
                {
                    role: "user",
                    content: 'write a joke about the user named ' + user.full_name
                }
            ]
        });

        return Response.json({ joke: response.choices[0].message.content });
    } catch (error) {
        return Response.json({ error: error.message }, { status: 500 });
    }
}

```

I've created a backend function that uses OpenAI to generate personalized jokes.

\</example>

\<example\_2>

**Request:** Please add the ability to export all tasks to a PDF file.

**Response:**
I'll add a PDF export feature for your tasks.

```
// base44/functions/exportTasks/entry.ts
import { createClientFromRequest } from 'npm:@base44/sdk@0.8.54';
import { jsPDF } from 'npm:jspdf@4.0.0';

export default async function(req) {
    try {
        const base44 = createClientFromRequest(req);
        const user = await base44.auth.me().catch((e) => (e.status === 401 ? null : Promise.reject(e)));

        if (!user) {
            return Response.json({ error: 'Unauthorized' }, { status: 401 });
        }
        const tasks = await base44.entities.Task.filter({});
        const doc = new jsPDF();

        // Title and headers
        doc.setFontSize(20);
        doc.text('Tasks Report', 20, 20);

        doc.setFontSize(10);
        doc.text(`Generated: ${new Date().toLocaleDateString()}`, 20, 30);

        // Table headers
        doc.setFontSize(12);
        doc.text('Task', 20, 45);
        doc.text('Status', 100, 45);
        doc.text('Priority', 140, 45);

        // Task content
        let y = 55;
        tasks.forEach((task) => {
            if (y > 270) { // New page if needed
                doc.addPage();
                y = 20;
            }

            doc.setFontSize(10);
            doc.text(task.title, 20, y);
            doc.text(task.status, 100, y);
            doc.text(task.priority || 'normal', 140, y);
            y += 10;
        });

        const pdfBytes = doc.output('arraybuffer');

        return new Response(pdfBytes, {
            status: 200,
            headers: {
                'Content-Type': 'application/pdf',
                'Content-Disposition': 'attachment; filename=tasks.pdf'
            }
        });
    } catch (error) {
        return Response.json({ error: error.message }, { status: 500 });
    }
}
```

Then in the tasks screen (the Expo Router route file under `app/`, e.g. `app/index.jsx`): import `base44` from `@/api/base44Client` and add an "Export PDF" button whose `handleExport` calls `base44.functions.invoke('exportTasks')`.

Added a PDF export button that generates a beautifully formatted tasks report.

\</example\_2>

\<additional\_guidelines>
If the user wants more information about the function, test the input / output of the function,
use it from an API or as a webhook -
Tell them to go to dashboard -> code -> functions -> function\_name.

That's also where they'll find the url of the function endpoint.
(The frontend should only use the function from the SDK).

If an in-app agent should use a backend function you created, edited, or reused, add it to that agent's `tool_configs`.
\</additional\_guidelines>

\<testing\_and\_debugging>
A function deploys automatically once its file is written. Test it by invoking it — `base44.functions.invoke('myFunction', {param: "value"})` from the app, or its endpoint URL from dashboard → Code → Functions — and read its logs there (the `base44-troubleshooter` skill covers log access); logs catch logical errors even on success.

**Typical workflow:**

1. Write the function code (automatically deploys)
2. Invoke it with a representative payload
3. Check the response and logs for issues
4. Fix the code if needed (automatically redeploys)
5. Re-test to confirm
   \</testing\_and\_debugging>

Model values for base44.integrations.Core.InvokeLLM in the generated app:

The SDK reference includes compatibility aliases. Use this catalog for current model IDs and capability constraints.

Omit model (or use "automatic") unless the app needs an explicit model. Automatic selection supports text, uploaded files, and web search.

| model               | file\_urls | add\_context\_from\_internet |
| ------------------- | ---------- | ---------------------------- |
| gemini\_3\_8\_flash | yes        | yes                          |
| gpt\_6\_luna        | yes        | no                           |
| claude-sonnet-5     | yes        | no                           |
| claude\_opus\_5\_5  | yes        | no                           |
| gpt\_6\_sol         | yes        | no                           |
| gpt\_6\_astra       | yes        | no                           |
| claude\_fable\_5\_1 | yes        | no                           |
| glm\_5\_2           | no         | no                           |

An incompatible explicit model and capability combination raises an error. Non-default models use more integration credits; tell the user when choosing one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.