Connecting your own MongoDB

Base44 supports connecting your own MongoDB database, so your apps’ runtime data lives in a cluster you own and control.

Complete this setup before you create any apps in the workspace. Base44 needs an empty workspace to enable the connection, and apps created beforehand cannot be moved onto your database afterwards.

Work through the 6 steps in order. Steps 3 and 4 are independent of each other, so you can do those in either order, but everything else builds on what came before.

Choosing your setup

There are 2 independent choices to make, and all 4 combinations are supported, including username and password over PrivateLink.

Decision	Either	Or
How Base44 authenticates	Username & password: a database user in your cluster	AWS IAM (passwordless): Base44’s IAM role, with no stored credential
How Base44 reaches you	IP allowlist: over TLS on the public internet, restricted to Base44’s addresses	AWS PrivateLink: private connectivity that never traverses the public internet

AWS IAM removes the shared secret entirely and is preferred where available. It requires an AWS-hosted cluster. AWS PrivateLink is the stronger network posture. It requires a MongoDB Atlas dedicated cluster hosted on AWS, in any supported region, and involves 2 coordination steps with Base44, so allow extra lead time.

Meeting the requirements

Check your cluster against these before you start. Base44 validates most of them when you save your connection, so a mismatch here shows up as a failure later.

Requirement	Value
Deployment type	Replica set
MongoDB version	7.0 or later. Compound wildcard indexes, used when you create the indexes, are new in version 7.0
Minimum storage	100 GB. Managing and extending capacity is your responsibility
Database name	`app_prod`. Base44 confirms the current name for your environment
TLS	Required, with valid certificates
Workspace state	No apps created yet
If using AWS IAM	Cluster hosted on AWS
If using AWS PrivateLink	MongoDB Atlas, dedicated tier, hosted on AWS in any supported region. Tell your Base44 contact which region your cluster is in before you start

Before you create your cluster:

Free and Flex clusters cannot use private endpoints, and dedicated tiers currently start at M10. Talk to your Base44 contact first if you run Amazon DocumentDB or self-managed MongoDB.
Set your region now rather than later. Moving a cluster to another region rebuilds all 3 nodes, and a private endpoint cannot be used until nodes are running in its own region again.

Step 1: Create the database

Create the cluster to match the requirements above, then create the database Base44 gives you. For production this is currently app_prod.

const byomDb = db.getSiblingDB("app_prod");

Collections are created on demand, so you do not need to create them yourself.

Step 2: Create the indexes

Base44 does not create or modify indexes on your cluster. All indexing is yours to manage, including the ones below. Run these against app_prod.

Two indexes need particular care:

support_access_ttl_idx must include expireAfterSeconds: 0. Base44 grants time-limited support access by writing an expiry timestamp onto app-user rows, and this TTL index is what removes them. Without that option it is an ordinary index and those rows never expire.
wildcard_first is a compound wildcard index, which requires MongoDB 7.0 or later.

const byomDb = db.getSiblingDB("app_prod");

byomDb.entitys.createIndexes([
  { key: { app_id: 1, entity_name: 1, is_deleted: 1, created_date: -1 },
    name: "app_id_1_entity_name_1_is_deleted_1_created_date_-1" },
  { key: { app_id: 1, entity_name: 1, is_deleted: 1, _id: 1 },
    name: "app_id_1_entity_name_1_is_deleted_1__id_1" },
  { key: { "data.$**": 1, app_id: 1, entity_name: 1, is_deleted: 1, created_date: -1 },
    name: "wildcard_first" }
]);

byomDb.app_users.createIndexes([
  { key: { app_id: 1, email: 1 }, name: "app_id_1_email_1" },
  { key: { email: 1, role: 1, created_date: -1 },
    name: "email_1_role_1_created_date_-1" },
  { key: { updated_date: -1 }, name: "updated_date_-1" },
  { key: { support_access_expires_at: 1 },
    name: "support_access_ttl_idx",
    expireAfterSeconds: 0 }
]);

Step 3: Set up network access

Choose the option that matches your decision above.

Using an IP allowlist

Add these Base44 ranges to your MongoDB IP access list:

74.220.48.0/24
74.220.56.0/24

Confirm the current ranges with your Base44 contact before you finalize your firewall rules.

Using AWS PrivateLink

Base44 runs in AWS us-west-2 (Oregon), so Base44’s side of the connection is always there. Your cluster does not have to be:

A cluster in us-west-2: The simplest and fastest path, with nothing extra to do.
A cluster in another AWS region: Supported, with one extra step and extra lead time while Base44 provisions the connectivity. Expect some added latency on database calls, and cross-region data transfer charges on your side. Tell your Base44 contact which region you are in before you start, so they can confirm they can reach it.

This needs 2 handoffs with Base44, and neither side can complete it alone. Keep the Atlas wizard open between steps 3 and 5. To set up AWS PrivateLink:

In Atlas, go to Network Access > Private Endpoint > Dedicated Cluster, then click Add Private Endpoint. Choose AWS and the region your cluster is in.
If your cluster is not in us-west-2, click Edit next to Accepted Endpoint Regions on the endpoint service Atlas just created, then add us-west-2. Do this before you send anything to Base44. Without it, Base44 cannot create the connection at all, and you never receive the ID in step 4.
Wait for Atlas to create a VPC endpoint service, which takes 3 to 5 minutes, then send the service name it shows to your Base44 contact. It looks like com.amazonaws.vpce.<your-region>.vpce-svc-xxxxxxxxxxxx. Do not fill in the Create New Endpoint form, because it asks for a VPC and subnets that belong to Base44 rather than you.
Wait for Base44 to create the matching interface endpoint and send you back a 22-character endpoint ID, which looks like vpce-01d2….
Back in Atlas, click Add Endpoint and choose Connect Existing Endpoint rather than Create New Endpoint, because the endpoint already exists on Base44’s side. Paste the ID you were sent, then wait for the status to show Available.

The 2 IDs are different things and easy to mix up. What you send Base44 is a long dotted service name containing vpce-svc-. What you receive is a short vpce-… with no -svc-.

Step 4: Set up database access

Choose the option that matches your authentication decision.

Using a username and password

Create a database user scoped to app_prod, and give it read and write access across the whole database. To add a database user:

In Atlas, go to Security > Database Access, then click Add New Database User.
Under Authentication Method, select Password, then set a username and password.
Under Database User Privileges > Specific Privileges, add one privilege: the role readWrite, the database app_prod, and the collection left blank.
Click Add User.

Leaving the collection blank grants read and write access on all collections in that database, which Base44 needs. Do not scope it to a single collection, because that causes a “not authorized to insert” error.

Using AWS IAM

Register Base44’s IAM role as a database user on your cluster. No password is created or stored, because Base44 mints short-lived credentials at connection time. To add Base44’s IAM role as a database user:

In Atlas, go to Security > Database Access, then click Add New Database User.
Under Authentication Method, select AWS IAM.
Under AWS IAM Type, select IAM Role.
Enter the ARN arn:aws:iam::789051085499:role/Base44-Access.
Under Database User Privileges > Specific Privileges, add one privilege: the role readWrite, the database app_prod, and the collection left blank.
Click Add User.

Step 5: Build your connection string

Atlas gives you a string that is not quite the shape Base44 needs, so you copy it from Atlas and then adjust it. Atlas asks 2 things in order, and the first is where the PrivateLink path usually goes wrong. Both paths end at Drivers, but the connection type you pick first is what decides whether you get the private host or the public one. To get your connection string from Atlas:

In Atlas, go to Clusters, then click Connect.
For Connection type, pick Private Endpoint if you set up PrivateLink, or the standard connection otherwise.
For Connection method, pick Drivers, then copy the string it shows.

Your network choice	Connection type	Host you should end up with
IP allowlist	Standard connection	`yourcluster.ab12c.mongodb.net`
AWS PrivateLink	Private Endpoint	`yourcluster-pl-0.ab12c.mongodb.net`

If you chose PrivateLink and your host has no -pl- in it, you have copied the public endpoint. It connects and validates successfully, and quietly defeats the purpose of the setup. Check for -pl- before you continue.

Adjust your copied string to match the line for your combination. Username and password with an IP allowlist:

mongodb+srv://USER:PASSWORD@yourcluster.ab12c.mongodb.net/app_prod?tls=true&retryWrites=true&w=majority

Username and password with PrivateLink:

mongodb+srv://USER:PASSWORD@yourcluster-pl-0.ab12c.mongodb.net/app_prod?tls=true&retryWrites=true&w=majority

AWS IAM with an IP allowlist:

mongodb+srv://yourcluster.ab12c.mongodb.net/?authMechanism=MONGODB-AWS&authSource=$external&tls=true

AWS IAM with PrivateLink:

mongodb+srv://yourcluster-pl-0.ab12c.mongodb.net/?authMechanism=MONGODB-AWS&authSource=$external&tls=true

The AWS IAM strings have no username or password, which is expected.

Rules your connection string must satisfy

Base44 rejects a string that breaks any of these outright, rather than warning you.

Rule	Notes
`tls=true` set explicitly	The most common failure. Atlas’s copied string does not include it, so append `&tls=true`
Database path `/app_prod`, or omitted	Any other database name is rejected
URL-encode special characters in the username or password	Password authentication only
No `tlsInsecure`, `tlsAllowInvalidCertificates`, `tlsAllowInvalidHostnames`, or `tlsDisableOCSPEndpointCheck`	Certificate validation cannot be disabled
No `tlsCAFile`, `tlsCertificateKeyFile`, or `tlsCRLFile`	Custom CA bundles and mTLS are not supported
No `srvServiceName`	The SRV service name cannot be customized
No `w=0`	Write acknowledgement cannot be disabled
Password authentication must include `USER:PASSWORD` and must not set `authMechanism=MONGODB-AWS`
AWS IAM must not include credentials, and must set `authMechanism=MONGODB-AWS` and `authSource=$external`

Base44 treats your connection string as a high-security secret. The raw value is stored only in encrypted secret storage and used server-side solely to establish the connection, and the settings screen and API show only a redacted form afterwards. Provide it only through your workspace settings, never by email or chat.

Step 6: Complete setup in Base44

Once your cluster, indexes, network access, and database access are ready, connect it to your workspace. To complete your setup:

Click your workspace name at the bottom left of your account.
Click Settings.
Click Overview.
Under Data hosting > Workspace MongoDB connection, select your Authentication method, either Username & password or AWS IAM (passwordless), to match your database access.
Paste your connection string. The database name is fixed to app_prod and cannot be edited.
Click Validate and save. Base44 connects to your cluster, runs a ping, then writes, reads back, and deletes one temporary document per validated collection. Nothing is saved if any check fails.
Once the status shows Validated, click Enable.
Create your apps only after the status shows Enabled.

Validation is not activation. Your runtime data routes to your database only after you complete the Enable step.

After setup

A few things change once your connection is live, and 2 of them cannot be undone without help.

Apps created after you enable the connection route their runtime entity and app-user data to your cluster. Base44 platform metadata, such as accounts, workspaces, billing, and app definitions, always remains on Base44-managed infrastructure.
You cannot change the connection from your workspace settings once it is enabled. Rotating a password or moving clusters is a managed migration handled with Customer Care.
You can disable the connection only before the workspace’s first app is created. After that, changes need a managed migration.

Troubleshooting

Base44 rejects a connection rather than accepting a broken one, so each failure comes with a specific message. Find yours below.

Message	Cause	Fix
MongoDB URI must explicitly set `tls=true`	Atlas string copied as-is	Append `&tls=true`
BYOM URI database path must be `/app_prod`	The wrong database in the path	Use `/app_prod`, or drop the path
Authenticated, but the database user is not authorized	The user is scoped too narrowly	Grant readWrite on `app_prod` with the collection field blank
Authentication failed	The wrong password, or the IAM role ARN is not registered as an AWS IAM Role user	Re-check your database access
Could not reach the cluster	The IP ranges are not allowlisted, or the private endpoint is not yet Available	Re-check your network access
Base44 cannot create the connection, and you never receive a `vpce-` ID	`us-west-2` is missing from your endpoint service’s Accepted Endpoint Regions	Add it, then ask your Base44 contact to try again
MongoDB URI host is not allowed	The host resolves to a private address Base44 cannot verify	Contact your Base44 contact
The enabled BYOM connection cannot be changed	You are editing an already-enabled connection	Contact Customer Care

If your error is not listed here, contact your Base44 contact and we will help you get connected.

Get started

SSO

SCIM

Members & access

Workspace settings

Choosing your setup

Meeting the requirements

Step 1: Create the database

Step 2: Create the indexes

Step 3: Set up network access

Using an IP allowlist

Using AWS PrivateLink

Step 4: Set up database access

Using a username and password

Using AWS IAM

Step 5: Build your connection string

Rules your connection string must satisfy

Step 6: Complete setup in Base44

After setup

Troubleshooting

​Choosing your setup

​Meeting the requirements

​Step 1: Create the database

​Step 2: Create the indexes

​Step 3: Set up network access

​Using an IP allowlist

​Using AWS PrivateLink

​Step 4: Set up database access

​Using a username and password

​Using AWS IAM

​Step 5: Build your connection string

​Rules your connection string must satisfy

​Step 6: Complete setup in Base44

​After setup

​Troubleshooting

Choosing your setup

Meeting the requirements

Step 1: Create the database

Step 2: Create the indexes

Step 3: Set up network access

Using an IP allowlist

Using AWS PrivateLink

Step 4: Set up database access

Using a username and password

Using AWS IAM

Step 5: Build your connection string

Rules your connection string must satisfy

Step 6: Complete setup in Base44

After setup

Troubleshooting