Connect an Atoms project to Supabase when you want the app to use a Supabase database, authentication, file storage or backend functions.

This guide takes you through the complete journey: prepare a Supabase account and project, authorize the correct organization, connect the project, check that the connection worked and disconnect it when needed.

How the connection works

Each Supabase project belongs to an organization, which controls who can access and manage the projects within it. When you connect Supabase to Atoms, you first authorize Atoms to access the organization you want to use, then select a project from that organization to connect.

Each Atoms project can be connected to one Supabase project at a time. However, the same Supabase project can be connected to more than one Atoms project.

Supabase and Atoms Cloud are alternative backend options. You cannot connect both to the same Atoms project at the same time.

Before you start

Before connecting Supabase, make sure that:

• You are the owner of the Atoms workspace that contains the project. Only the workspace owner can authorize, connect, or disconnect Supabase.
• You have a Supabase account, or are ready to create one during setup.
• You have permission to authorize the Supabase organization and access the project you want to connect with.
• The Agent has finished its current task and Race Mode is turned off.
• Your browser allows pop-up windows from Atoms.
• Your Atoms project is not already connected to Atoms Cloud.

If you are trying this connection for the first time, consider using a test project while you learn the process.

Never paste a Supabase password, API key, access token, or other credential into Chat.

Connect Supabase

Open the Supabase connector

1. Open the project you want to connect.
2. Click project name, at the top right of the chat panel.
3. Select Connectors in the drop down menu that appears.
4. Find Supabase in the list of available connectors, and click connect.

You can also open Settings → Connectors → Supabase and select Connect.

Open Settings → Connectors and select Connect for Supabase.

Authorize Atoms in Supabase

If Organizations already shows the Supabase organization you want to use, it has already been authorized. You can continue to Choose the Supabase project.

1. Atoms opens a Supabase authorization window. Sign in to the Supabase account you want to connect to, or create a new account if needed.
2. Check that you are signed in to the correct Supabase account, then select the organization you want Atoms to access.
3. Review the permissions requested by Atoms. To see every permission, select Show detailed permissions. If you agree, select Authorize Atoms.
4. Return to Atoms and wait for the Connect success message.
5. In Atoms, open Connectors → Supabase and confirm that the organization appears under Organizations.

Atoms requests read and write access to Database, Secrets, Auth, Edge Functions, Environment, Projects, PostgREST and Storage. It also requests read access to Organizations and Domains. These permissions allow Atoms to connect and manage the supported Supabase services used by your project.

This authorization applies to the selected Supabase organization and is not limited to the Supabase project you later connect to the current Atoms project. Atoms cannot access organizations or projects that the connected Supabase account itself cannot access, and Supabase permissions may impose additional restrictions.

Review the organization and permissions before authorizing Atoms.

Choose the Supabase project

1. Under Organizations, expand the organization you authorized.
2. Under Projects, find the active Supabase project you want to connect.
3. If the organization you need is not listed, select New Organization and authorize it. This does not create a new Supabase organization; it lets you authorize another organization that already exists in your Supabase account.
4. If you do not have a project yet, select Create Project and create one in Supabase. Wait until the project is active and ready to use, then return to Atoms and select Update to refresh the project list.
5. Next to the project you want to use, select Connect.

Choose a Supabase project from the authorized organization.

Confirm the project

1. In the confirmation window, check the organization and project shown under Supabase Project.
2. If needed, use Supabase Dashboard or View Tables to confirm that you selected the correct project.
3. Select Connect.
4. Atoms adds a Supabase connection item to the project Chat. Keep the page open and wait for it to finish before asking the Agent to build a database, authentication, storage or backend feature.

Confirm the selected Supabase project before connecting.

Check that the connection worked

1. Open Settings → Connectors → Supabase.
2. Confirm that the correct organization and Supabase project are shown as connected.
3. Select Dashboard or Tables and check that it opens the same project in Supabase.

The connected project panel may also include links to Manage Users, SQL Editor, Edge Functions, and Manage Secrets. You only need to use the areas relevant to the features you are building.

Review the connected Supabase project and its management links.

Test that your app can save data

Connecting Supabase does not add a database feature to your app by itself. In Chat, ask the Agent to build the feature you want and use the connected Supabase project to store its data. After the Agent finishes, test the complete journey.

1. In Chat, describe the feature you want, what information it should save and where users should see that information again. Tell the Agent to use the connected Supabase project.
2. Wait for the Agent to finish building the feature.
3. In the App Viewer, use the feature as a user would and enter harmless test data. Do not use personal, confidential or sensitive information.
4. Refresh the App Viewer or reopen the feature. Confirm that the saved information remains and appears in the correct place.
5. Open Settings → Connectors → Supabase, select Tables and confirm that the matching record appears in the correct table.

If the feature allows users to edit or delete saved information, test those actions as well and confirm that the results are correct in both the app and Supabase. Whether changes made directly in Supabase appear immediately in the app depends on how the app was built.

Disconnect Supabase

Disconnect Supabase when you no longer want the current Atoms project to use the connected Supabase project.

1. Open Settings → Connectors → Supabase.
2. Confirm that you are viewing the connection for the correct Atoms project.
3. Select Disconnect Project.
4. Wait for the Supabase disconnection item in Chat to finish.
5. Reopen Connectors → Supabase and confirm that the project is no longer shown as connected.

Disconnecting removes the connection from the current Atoms project. It does not delete the Supabase project or its data, and it does not remove the authorization for the Supabase organization.

Any features in your Atoms project that depend on Supabase may stop working after you disconnect it. If your app is already published, you may need to update the published version before the change takes effect. Test both your project and the live app after disconnecting.

Disconnecting Supabase from one Atoms project does not affect other Atoms projects connected to the same Supabase project.

FAQ

Why has my Supabase connection stopped working?

1. Open the Supabase Dashboard and check the affected project's status. A low-activity Free Plan project may be paused after a seven-day period.
2. If it is paused, select Resume project and wait until Supabase reports that it is active.
3. Return to Atoms, open the project's Connectors panel, and verify the Supabase connection. Retry the failing action once.
4. If Supabase is already active, capture the exact Atoms or Supabase error and check whether the connection is shown as disconnected or expired. Reconnect only when the status indicates that it is needed.

Do not rotate keys or create a replacement project until you know the cause and have protected existing data. If the failure continues, contact Support with the Chat Link, time and timezone, connection status, and sanitized error screenshot.

External reference: Supabase — Project Pausing

How do I reconnect a Supabase project that was paused?

1. Sign in to the correct Supabase organization and open the paused project.
2. Select Resume project and wait until its status is active. Current Supabase guidance says low-activity Free Plan projects may be paused after a seven-day low-activity period.
3. Return to Atoms and open the project's Connectors panel. Confirm that Supabase is connected, then retry the affected operation.
4. If Atoms still shows the connector as disconnected or expired, reconnect it and complete the requested authorization.

Do not create a new Supabase project or rotate credentials until existing data is protected. If reconnection fails, provide Support with the Chat Link, Supabase project status, time and timezone, and a sanitized error screenshot.

External reference: Supabase — Project Pausing