Connecting data

How to connect Airtable

September 15, 2026
How to connect Airtable

To connect an Airtable base to TeleportHQ, you need two things from Airtable: the Base ID and a Personal Access Token. Enter both in Data Sources → Add Data Source → Airtable and click Fetch Airtable Schema. TeleportHQ adds every table in the base to your project, so you can show its records on your pages.

Before you start

  • You need an Airtable account with access to the base, for example a base called "Café menu".
  • Each project can have one Airtable connection. Once it's connected, the Airtable card shows Already connected.
  • Connecting Airtable doesn't turn a TeleportHQ website into a web app.

Steps

1. Find your Airtable Base ID

  1. Open your base in Airtable.
  2. Look at the address in your browser. It looks like https://airtable.com/appAbC123dEf456/tbl….
  3. Copy the part that starts with app, for example appAbC123dEf456. That is your Base ID.

2. Create a personal access token in Airtable

  1. Go to https://airtable.com/create/tokens and click Create new token.
  2. Give your token a name, for example TeleportHQ.
  3. Add the scope data.records:read.
  4. Add the scope schema.bases:read.
  5. To also add or change records and tables from TeleportHQ, add data.records:write and schema.bases:write. Reading the base needs only the two scopes above.
  6. Select the base (or bases) you want to connect.
  7. Click Create token.
  8. Copy the token and keep it private: it gives access to your Airtable data.

In the TeleportHQ Airtable form, the Where to find this? link next to Personal Access Token opens a window with the same steps, titled Finding Your Personal Access Token.

The TeleportHQ window Finding Your Personal Access Token, with the steps to create an Airtable token and its two required scopes

3. Add the Airtable data source in TeleportHQ

  1. In the left sidebar, click Data Sources (the database icon).
  2. In the Data Sources panel, click + (tooltip Add Data Source).
  3. Click the Airtable card. A panel titled Airtable opens with the section Setup Airtable Connection.
  4. In Data Source Name, type a name, for example Cafe menu. Use letters, numbers, spaces and underscores.
  5. Paste your Base ID into Base ID.
  6. Paste your token into Personal Access Token.
  7. Click Fetch Airtable Schema. It stays greyed out until both fields are filled.
The TeleportHQ Airtable setup form with the Base ID and Personal Access Token fields and the Fetch Airtable Schema button highlighted

TeleportHQ tests the connection, adds all tables and closes the panel. If this is the project's first data source, a window titled IMPORTANT appears; click I understand. Each field's Where to find this? link repeats these steps inside TeleportHQ.

Check that it worked

The Airtable connection appears as a card in the Data Sources panel. Click it to see your tables under Confirmed Data Sources. Click View Data on a table to see its records. Then show them on your pages.

Troubleshooting

"Failed to test connection. Please verify that the Personal Access Token has the required permissions (data.records:read and schema.bases:read) and that the Base ID is correct." The token is missing a scope, doesn't include this base, or the Base ID is wrong. In Airtable, edit the token: add both scopes and select the base. Check that the Base ID starts with app. Then click Fetch Airtable Schema again.

"Failed to fetch Airtable schema. Please verify that the Personal Access Token has the required permissions (data.records:read and schema.bases:read) and that the Base ID is correct." The connection worked, but TeleportHQ couldn't read the base's tables. Check that the token has schema.bases:read and includes this base.

Saving a record or a field change from TeleportHQ fails The token can only read. In Airtable, edit the token and add data.records:write (records) and schema.bases:write (tables and fields).

A new Airtable table doesn't appear in TeleportHQ Tables added after connecting show up after a refresh. See Refresh, edit or remove a data source.

Good to know

  • Your token becomes a Secret. When you save, TeleportHQ stores the token in the project's Secrets. See Keep passwords and API keys safe.
  • Table structure: from TeleportHQ you can create Airtable tables, and add, change or remove fields. Links between tables are not supported.
  • What the scopes allow. TeleportHQ sends record changes (add, edit, delete) and table or field changes to Airtable with your token, so those need the write scopes. Showing the base on your pages needs only data.records:read and schema.bases:read.
Share

Related Articles

What are data sources, and which ones can I connect?

A data source is a connection that brings content from a database, spreadsheet, API or headless CMS into your TeleportHQ project, so your pages show real data instead of typed text; you manage them in the editor's Data Sources panel, and connecting one keeps a website a website.

How to use a Google Sheet as data

To use a Google Sheet in TeleportHQ, share the sheet so anyone with the link can view it, paste its URL in Data Sources → Add Data Source → Google Sheets, load the preview and click Save Data Source.

How to keep passwords and API keys safe (Secrets)

TeleportHQ stores passwords, tokens and API keys as project Secrets, which the project owner manages in Project settings → Data & code → Secrets and links to credential fields with the plug button, instead of typing the value into each data source.

How to show data from a data source on your pages

In TeleportHQ you show data on a page by binding elements to it: click the plug icon next to a field in the right panel, pick a value in the Select Dynamic Property panel and click Bind property, or use an Array Mapper to repeat a design for every item in a list.

How to refresh, edit or remove a data source

In TeleportHQ, click a data source card in the Data Sources panel to rename it, change its connection details or refresh its tables, and use the card's trash button to delete it, which unbinds every element that uses it.