Airtable

Your Airtable bases: find a record, create or update a row without duplicates, attach an email file to it and comment a record.

An Airtable connection lets the Airtable node read, create and update rows in your bases without duplicates, drop email attachments into an attachment field and comment a record. The same connection feeds the Airtable row changed trigger, which checks a table at a regular interval and starts a workflow for each new or changed row.

The connection holds a personal access token. It is encrypted at rest, applied by the server at call time, and never appears in a workflow.

At a glance

• Identifier: airtable
• Family: Service
• Set up by: A member (personal) or an administrator (shared with the organisation)
• Authentication: API key or token
• Credential type: service:airtable
• Official API documentation: https://airtable.com/developers/web/api/introduction
• API base URL: https://api.airtable.com
• Rate limit applied by Mankomail: 4 requests per second and per connection; up to 4 attempts on a 429 or a 5xx
• Webhook signature: X-Airtable-Content-MAC header, HMAC-SHA256 of the raw body
• Connection test: Yes

Step by step

The same steps are shown in the connection form of the app.

1. Sign in to Airtable, open airtable.com/create/tokens, then click “Create new token”.
2. Give the token a clear name: it shows up in the record revision history (“Someone via <name>”).
3. Under “Scopes”, add data.records:read, data.records:write and schema.bases:read — plus data.recordComments:write to post comments. The trigger polls the table: it needs no extra permission.
4. Under “Access”, click “Add a base” and pick the bases involved: the token sees nothing else.
5. Click “Create token” and copy it right away — Airtable shows it once — then paste it below and test the connection.
6. The signing secret is only needed for Airtable webhooks: Airtable returns it once, when the webhook is created. Leave it empty otherwise.

Connection fields

Field	Kind	Required	Notes
Personal access token (token)	Secret — never shown again	Yes	It acts as the account that created it: if that person loses access to a base, the workflows stop.
Webhook signing secret (macSecret)	Secret — never shown again	No	Optional. The “macSecretBase64” Airtable returns when the webhook is created, and never shows again.

Before you start

• You need an Airtable account with access to the bases you want to automate. Personal access tokens are created by each user at airtable.com/create/tokens; the legacy API keys (key…) no longer work.
• The token acts as the account that created it. If that person loses access to a base or leaves the organisation, the workflows that use the token stop. For a team, create the token from a dedicated service account.
• To write rows, the account must have at least editor rights on the base. The editor shows each base's permission level (read, comment, edit, create…) next to its name, which tells you in advance why a write would be refused.
• The Airtable row changed trigger needs a Last modified time (or Created time) field in the watched table. Add it in Airtable before configuring the trigger.

Permissions

Airtable calls these permissions scopes. Tick only what you use.

Scope	Required	What it is used for
data.records:read	Yes	Search, Get a record, List a record’s attachments, and every check of the Airtable row changed trigger.
data.records:write	Yes	Create, Create or update, Update, Delete and Upload the attachments.
schema.bases:read	Yes	List the bases, Get a base schema, and every picker of the editor (base, table, view, field). Without it, no list fills in.
data.recordComments:write	Only to comment	The Comment operation.
data.recordComments:read	No	Suggested by the in-app guide; no current operation reads comments.
webhook:manage	No	Suggested by the in-app guide for triggers; the Airtable row changed trigger works by polling and does not use it.
user.email:read	No	Lets the connection test display the account’s email instead of its Airtable user id.

Under Access, add every base the workflows must reach: the token sees nothing else.

Add the connection

1. Open Connections. In the Third-party services section, find the Airtable card and click Connect.
2. Give the connection a Name: it is what you will read in a node’s connection picker.
3. Choose the Scope: Personal (only you can see and use it) or Organisation (the whole organisation uses it; only an administrator can create one).
4. Paste the token, leave the webhook signing secret empty, and click Create the connection.
5. Back in the list, click Configure on the new connection, then Test the connection.

The test calls GET /v0/meta/whoami, then GET /v0/meta/bases:

• if both answer and at least one base is reachable, it shows The connection works followed by the account email (with user.email:read) or the Airtable user id;
• if the token answers but reaches no base, the test fails and names schema.bases:read as missing. The usual cause is not the scope but the Access list: no base was added to the token;
• for an OAuth-style token that reports its scopes, the test lists the missing required scopes.

In a node, pick the connection in Airtable connection, then go down the cascade: Base → Table → View or Field. Changing the base empties the table. Every picker also accepts an id typed by hand or a pasted Airtable URL (https://airtable.com/appXXXX/tblYYYY/viwZZZZ). Field pickers are filtered by what the operation accepts: only attachment fields for an upload, only non-computed fields as a merge key. The workflow stores ids (app…, tbl…, fld…, viw…), so renaming a column in Airtable breaks nothing.

To replace the token, open Configure, paste the new value and save; a secret field left empty keeps the current value. Delete is refused while a published workflow uses the connection: unpublish it or switch it to another connection first.

Webhooks

The Airtable row changed trigger does not use Airtable webhooks: it polls.

• It is armed when the workflow is published. Its first position is “now”: publishing never replays the table’s history, and republishing never resets the position.
• Check every (minutes) defaults to 15, accepts 5 to 1,440, and can never go below the instance floor (INTEGRATION_POLL_MIN_MINUTES, 5 minutes by default — see environment variables).
• Each check reads at most one page of rows; the rest waits for the next check. Each row becomes one run, with its data under data.airtable. The deduplication key is derived from the row and its modification time, so a check repeated after an incident does not create a second run.
• On Airtable’s free plan, the monthly API call quota is low: a short interval can exhaust it quickly.

The connection form also has a Webhook signing secret field. Mankomail verifies Airtable’s X-Airtable-Content-MAC header (hmac-sha256= followed by an HMAC-SHA256 of the raw body, keyed with the base64-decoded macSecretBase64), but no current trigger receives Airtable webhooks. Leave the field empty.

Common errors

Message or code	Cause	What to do
Test: “the service rejects the key” (integration.unauthorized)	Token revoked, mistyped, or expired.	Create a new token and replace it in Configure.
Test: “the token is missing some required permissions (schema.bases:read)”	The token reaches no base (nothing under Access), or an enterprise setting blocks API access.	Add the bases to the token at airtable.com/create/tokens, then test again.
Test: “the token is missing some required permissions (…)” with other scopes	The token reports its scopes and some required ones are missing.	Add data.records:read, data.records:write and schema.bases:read.
Test: “the service quota is exceeded” (integration.rate_limited)	Airtable answered 429.	The token is fine: try again in a moment.
integration.unauthorized during a run	401 or 403: token revoked, or a scope missing for this operation (for example data.recordComments:write for Comment).	Widen the token’s scopes or replace it. Retrying will not help.
integration.not_found	404: the base, table or record does not exist, or the base is not in the token’s Access list.	Check the ids and the token’s access.
integration.rejected	400 or 422: Airtable refused the body (unknown field, wrong value type, non-unique upsert key, value not in a select list without automatic conversion).	Fix the node settings; the same request will be refused again.
integration.rate_limited	429 after retries. Mankomail sends at most 4 requests per second per connection, retries up to 4 times and honours Airtable’s 30-second wait.	Transient: the engine resumes the step later. Spread out workflows that share the same token.
integration.unavailable	5xx, 409 or network failure, after retries.	Transient: the engine resumes the step later.
integration.connection_unusable	The connection was deleted, is not active, is out of your scope (a personal connection of another member), or belongs to another service.	Pick a valid connection in the node.
Notification “The trigger of workflow … is broken”	A check of Airtable row changed failed permanently. The reason shown follows the code: integration.unauthorized (reconnect), integration.not_found (the base or table is gone), integration.rejected (check the trigger settings), integration.poll_misconfigured (no connection selected), integration.poll_failed (for example a base, table or Date field left empty). One notification per outage; temporary failures (429, 5xx) notify no one.	Fix the cause, then wait for the next check: the trigger resumes on its own.

Nodes that use this connection

• Airtable row changed — trigger.airtable
• Airtable — airtable.api