Skip to content
Docs
Docs & knowledge

Airtable

Let hires look through, search, add and update records in your Airtable bases.

Explore 7 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Airtable, a hire can:

  • list the bases and tables it can use, with each table's fields,
  • list a table's records, from a view if you like, filtered and sorted,
  • search records by the words in their text fields,
  • read a record with every field,
  • add records (up to 10 at once) and change some fields of a record.

1. Choose how Roster signs in

Straight there: airtable.com/create/tokens.

  • A personal access token (quickest). At airtable.com/create/tokens, click Create token, add the scopes data.records:read, data.records:write and schema.bases:read, add the bases hires should work in, and copy the token. A read-only hire only needs the two read scopes.
  • An OAuth integration of yours. At airtable.com/create/oauth, register an integration with the same scopes, set its redirect URL to the address Roster shows on the connection (it ends in /api/integrations/airtable/oauth/callback), and copy its client ID and secret. When you connect, Airtable asks which bases to share.

What hires change shows as the token's or the integration's owner.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Airtable and choose it.
  2. How Roster signs in: pick the way you chose above. Only its fields are shown.
  3. Paste the token, or the integration's client ID and secret.
  4. Click Connect. With an OAuth integration, then click Connect with Airtable and choose the bases.

Roster checks the key when you click Connect. If what you paste doesn't look like a key (a personal access token starts with pat), the form says so straight away. Once it's accepted, the connection shows Connected as the email of the Airtable account the token belongs to. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on Airtable:

  • Read only: it can list bases, tables and records, search and read them, and nothing else.
  • Read and write: it can also add records and change their fields.
  • Bases: base names or ids (they start with app), one per line. Leave it empty for every base the token reaches.
  • Tables: table names or ids (they start with tbl). Leave it empty for every table in those bases. Anything outside the lists is refused.

Hires refer to bases, tables and fields by the names you see in Airtable, and to records by their id (it starts with rec). When a hire fills in a select field with an option that doesn't exist yet, Airtable adds the option.

Watching for changes

A hire's responsibility can watch Airtable: when records in its tables change, the hire is woken with the list. It watches up to 10 tables, so list the ones that matter. Add a Last modified time field to a table for exact times.

If something goes wrong

  • "Couldn't find that": the base isn't added to the token, or the table's name changed.
  • "Rate limit is used up": Airtable allows 5 requests a second per base and then asks for a 30-second pause. The hire waits and tries again.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Airtable and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

At airtable.com/create/tokens: add scopes data.records:read, data.records:write and schema.bases:read, and the bases hires may use.

For: How Roster signs in: Personal access token.

OAuth 2.0

From the OAuth integration you registered at airtable.com/create/oauth.

For: How Roster signs in: An OAuth app of yours.

Requested scopes:

  • data.records:read
  • data.records:write
  • schema.bases:read

When making a key, use these permissions from the connection guide:

  • data.records:read
  • data.records:write
  • schema.bases:read

Connection fields

Airtable connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		A token is quickest. An OAuth app of yours lets Airtable show Roster by name.

Choices: Personal access token (token); An OAuth app of yours (oauth).

Starts with: token.

Personal access token
token
Required · sealed secret		At airtable.com/create/tokens: add scopes data.records:read, data.records:write and schema.bases:read, and the bases hires may use.

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From the OAuth integration you registered at airtable.com/create/oauth.

Shown when signIn: oauth.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Airtable per-hire limits
FieldWhat to provide
Bases
bases
Optional		Base names or ids (they start with app). Leave empty for every base the token reaches.
Tables
tables
Optional		Table names or ids (they start with tbl). Leave empty for every table in those bases.

Actions

7 actions: 5 only read and 2 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

7 of 7 actions. Open an action for its arguments and full input schema.

list_basesRead only

The Airtable bases this hire can use.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_tablesRead only

A base's tables with their fields and types.

Approval: Uses your workspace and hire approval settings.

Arguments for list_tables
ArgumentTypeDetails
baseRequiredstringbase name or id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "base": {
      "type": "string",
      "minLength": 1,
      "description": "base name or id"
    }
  },
  "required": [
    "base"
  ]
}
list_recordsRead only

A table's records, optionally from a view, filtered with an Airtable formula (e.g. AND({Status}="Open", {Amount}>100)) and sorted by a field.

Approval: Uses your workspace and hire approval settings.

Arguments for list_records
ArgumentTypeDetails
baseRequiredstringbase name or id
tableRequiredstringtable name or id
viewOptionalstringa view's name
formulaOptionalstringan Airtable formula; records where it's true
sort_byOptionalstringa field's name
directionOptional"asc" | "desc"See input schema below.Default: "asc"
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "base": {
      "type": "string",
      "minLength": 1,
      "description": "base name or id"
    },
    "table": {
      "type": "string",
      "minLength": 1,
      "description": "table name or id"
    },
    "view": {
      "description": "a view's name",
      "type": "string"
    },
    "formula": {
      "description": "an Airtable formula; records where it's true",
      "type": "string",
      "maxLength": 2000
    },
    "sort_by": {
      "description": "a field's name",
      "type": "string"
    },
    "direction": {
      "default": "asc",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "base",
    "table"
  ]
}
search_recordsRead only

Find records whose text fields contain some words (or one field, if named).

Approval: Uses your workspace and hire approval settings.

Arguments for search_records
ArgumentTypeDetails
baseRequiredstringbase name or id
tableRequiredstringtable name or id
textRequiredstringSee input schema below.
fieldOptionalstringonly this field
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "base": {
      "type": "string",
      "minLength": 1,
      "description": "base name or id"
    },
    "table": {
      "type": "string",
      "minLength": 1,
      "description": "table name or id"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "field": {
      "description": "only this field",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "base",
    "table",
    "text"
  ]
}
get_recordRead only

One record with every field.

Approval: Uses your workspace and hire approval settings.

Arguments for get_record
ArgumentTypeDetails
baseRequiredstringbase name or id
tableRequiredstringtable name or id
recordRequiredstringrecord id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "base": {
      "type": "string",
      "minLength": 1,
      "description": "base name or id"
    },
    "table": {
      "type": "string",
      "minLength": 1,
      "description": "table name or id"
    },
    "record": {
      "type": "string",
      "pattern": "^rec[A-Za-z0-9]{14}$",
      "description": "record id"
    }
  },
  "required": [
    "base",
    "table",
    "record"
  ]
}
create_recordsRead and write

Add records to a table (up to 10 at once), each as field name → value. Option names that don't exist yet are added to the field.

Approval: Uses your workspace and hire approval settings.

Arguments for create_records
ArgumentTypeDetails
baseRequiredstringbase name or id
tableRequiredstringtable name or id
recordsRequiredobject[]See input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "base": {
      "type": "string",
      "minLength": 1,
      "description": "base name or id"
    },
    "table": {
      "type": "string",
      "minLength": 1,
      "description": "table name or id"
    },
    "records": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "description": "field name → value; text, numbers, true/false, dates like 2026-11-30, option names, lists of record ids for links"
      }
    }
  },
  "required": [
    "base",
    "table",
    "records"
  ]
}
update_recordRead and write

Change some fields of a record. Fields not given stay as they are.

Approval: Uses your workspace and hire approval settings.

Arguments for update_record
ArgumentTypeDetails
baseRequiredstringbase name or id
tableRequiredstringtable name or id
recordRequiredstringrecord id
fieldsRequiredobjectfield name → value; text, numbers, true/false, dates like 2026-11-30, option names, lists of record ids for links
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "base": {
      "type": "string",
      "minLength": 1,
      "description": "base name or id"
    },
    "table": {
      "type": "string",
      "minLength": 1,
      "description": "table name or id"
    },
    "record": {
      "type": "string",
      "pattern": "^rec[A-Za-z0-9]{14}$",
      "description": "record id"
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "field name → value; text, numbers, true/false, dates like 2026-11-30, option names, lists of record ids for links"
    }
  },
  "required": [
    "base",
    "table",
    "record",
    "fields"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Zoho CRM

Leads, contacts, deals and activities in Zoho CRM.

Baserow

Open-source no-code database: tables, rows and views.

On this page

1. Choose how Roster signs in2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference