Airtable connector setup

This page is the setup half — creating the OAuth integration Airtable needs in its own developer console and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Airtable.

1. Create the OAuth integration in the Airtable developer console

1. Open the Airtable developer hub and create a new OAuth integration — this is your own integration, not Botseon's.

2. Under redirect URL, paste the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

   http://127.0.0.1:3000/api/oauth/airtable/callback
   

3. Save. The console shows you a Client ID and a Client secret — copy both now.

2. Scopes

Request the narrowest pair that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

• data.records:read — read your bases and records; no writes.
• schema.bases:read — see your bases, tables and fields; no writes.
• data.records:write — create and update records, on top of what the read pair covers.

3. Enter the integration

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug airtable \
  --client-id <the client ID from step 1> \
  --auth-url https://airtable.com/oauth2/v1/authorize \
  --token-url https://airtable.com/oauth2/v1/token \
  --configured-by <your user id>

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug airtable says whether an integration is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. What this connector does and does not do

Every read tool answers from the base, table and record ids the model supplies — the connector holds no base of its own, so list_bases is usually the first call a bot makes.

• airtable.list_bases — the bases this connection can see.
• airtable.get_base_schema — a base's tables, each with its fields and their types.
• airtable.list_records — records from a table, optionally narrowed by a view or a filterByFormula expression, capped at 100 per call.
• airtable.get_record — one record by id.
• airtable.create_record — adds a record to a table with the given fields. Tagged write, so it asks for approval before it runs; the approval card names the table the record is created in.
• airtable.update_record — changes a record's fields. Tagged write for the same reason; the approval card names the record being changed.

If Airtable is rate-limiting the connection it answers with a 429 and a Retry-After header; the connector reports this as a rate_limit error carrying that delay rather than retrying silently, so a member may see a tool call fail with "Airtable is rate-limiting this connection" and can expect it to succeed again shortly after.

This connector's catalogue row ships available: false: it stays disabled until the live smoke runs at turn-on.