Skip to main content

Airtable Setup

Configuring a custom Airtable OAuth integration for use with Caddi

Airtable lets you register an OAuth integration in Builder Hub, on any plan. This guide covers registering it, choosing scopes, and connecting it to Caddi.

Airtable refresh tokens expire after 60 days of non-use. If a connection sits idle past that, the authorization is effectively revoked and the user has to reconnect — there's no silent recovery. Worth knowing if you set up a loop that only runs occasionally.

Before you start

You'll need:

  • Owner or Creator permissions in Airtable — available on all plan types

  • Owner or Admin access to your Caddi organization

  • On Airtable Enterprise: API access for third-party integrations enabled in the admin panel, or the integration will not work regardless of configuration

Step 1: Register the OAuth integration in Builder Hub

  1. Go to airtable.com/create/oauth, or from the Airtable home screen click your profile icon → Builder Hub → OAuth integrations → Register an OAuth integration.

  2. Integration name — Caddi

  3. Redirect URL — enter https://app.trycaddi.com/oauth-callback. HTTPS is required; multiple URLs are allowed.

  4. Select the Scopes (see below).

  5. Fill in the support information fields. Other users cannot authorize the integration until these are complete — an easy thing to skip and then puzzle over.

  6. Copy the Client ID.

  7. Click Generate a client secret and copy it immediately. Airtable states the secret is not recoverable.

Step 2: Choose scopes

Airtable's scope names are explicit about what they grant. The set below gives full read and write on data and schema without touching enterprise administration.

Do not request anything prefixed enterprise., and avoid workspacesAndBases:write, :manage, or .shares:manage. Those are the administration tier.

  1. data.records:read and data.records:write — see and modify record data

  2. data.recordComments:read and data.recordComments:write — record comments

  3. schema.bases:read and schema.bases:write — read and modify base structure

  4. webhook:manage — only if a loop uses webhooks

  5. workspacesAndBases:read — add this if Caddi needs to list your bases for a picker

  6. user.email:read — add this only if you need to identify the user

If you skip schema.bases:write, Caddi can read and write records but cannot add fields or tables.

Step 3: Configure Airtable in Caddi

This step must be completed by a Caddi organization owner or admin.

  1. In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.

  2. Find Airtable in the list and click Configure.

Enter the following values:

  • Client ID — from your Airtable OAuth integration

  • Client Secret — the value shown once when you generated it

  • OAuth Scopes — space-separated list matching what you selected on the integration. Leave blank to use Caddi's defaults.

Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.

Step 4: Connect your account

  1. Go back to the My Connections tab and find Airtable.

  2. Click Connect + and sign in to Airtable.

  3. Choose what to grant. Airtable lets the user pick individual bases, one or more whole workspaces (covering current and future bases in them), or everything. Selecting workspaces rather than individual bases means new bases work without reconnecting.

  4. Approve the request. You'll be returned to Caddi with the connection active.

How the connection behaves

  • Grants are user-chosen and can be narrow. Caddi sees only the bases the user picked. If a base is missing, the user needs to reconnect and widen the grant.

  • Access tokens last 60 minutes and refresh automatically.

  • Refresh tokens rotate on every use and expire after 60 days of non-use. An idle connection past 60 days requires a fresh authorization, not a refresh.

  • A custom connection replaces the standard one. Members of your organization will only see the option to connect through your app.

  • Revoking access. Delete the integration in Builder Hub, or have users revoke it from their Airtable account. Enterprise admins can also revoke grants from the admin panel.

Troubleshooting

Other users can't authorize the integration

The support information fields in Builder Hub aren't complete. Airtable gates third-party authorization on them.

A loop can't find a base the user has access to

That base wasn't included in the grant. Have the user reconnect and select the base, or select the whole workspace so future bases are covered too.

A connection that hadn't run in a couple of months stopped working

The refresh token passed its 60-day idle expiry. The user needs to reconnect. If the loop runs infrequently by design, consider scheduling a lightweight run inside the window.

The client secret was lost

Airtable secrets are not recoverable. Generate a new one in Builder Hub and update the configuration in Caddi.

The integration doesn't work at all on an Enterprise plan

API access for third-party integrations is disabled in the Airtable enterprise admin panel. An Airtable admin needs to enable it.

Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.

Automation ideas

Law Firms

Intake form → tracked matter row

Caddi writes new enquiries into your Airtable intake base with the fields normalized, and creates the follow-up task.

Airtable status change → downstream action

When a record's status changes, Caddi carries out the next step — creating the matter, sending the engagement letter, or updating the DMS.

RIAs

Prospect pipeline → CRM sync

Caddi keeps your Airtable pipeline and CRM records aligned so the same prospect isn't tracked twice with different detail.

Related Articles
Did this answer your question?