Skip to content

README.md

113 lines · 5.1 KB · Markdown
Raw

@kody/airtable

Intent

Provide reusable, account-agnostic Airtable helpers so Kody agents can read and update bases, tables, records, and comments through a saved airtable / airtable-* OAuth integration or a personal access token — without hand-rolling REST. Mutations are previewable with dryRun: true and only run live after confirm: true.

This listing is meant to be forked. After you fork, connect your Airtable workspace. Do not treat the live @kody/airtable package storage as yours.

Share this listing as https://kody.codes/@kody/airtable

What it does

  • List or inspect bases, tables, records, and comments
  • Create, update, or delete records after explicit confirmation
  • Create comments after explicit confirmation
  • Call an unwrapped Airtable REST path through ./request
  • Connect more than one Airtable account via integrationName / account

Prerequisites / setup

Airtable has no built-in Kody OAuth app. Choose one lane:

LaneWhen to useCredential
OAuth (recommended)Multi-account, refresh tokens, shared helpersSaved integration airtable or airtable-<purpose>
Personal access tokenFastest for a single workspace / personal scriptsUser secret airtablePat (or airtablePat-<purpose>)

Both lanes send Authorization: Bearer …. Required API host: api.airtable.com. Approve it in the account secrets UI.

Lane A — BYO OAuth
  1. Register an OAuth integration at https://airtable.com/create/oauth
  2. Set the redirect URI exactly to https://kody.codes/connect/oauth
  3. Generate a client secret (Airtable token exchange uses HTTP Basic when a secret exists). Enable PKCE — Airtable requires S256 PKCE on every authorize request.
  4. Under Scopes, enable the scopes this package uses (data.records:read, data.records:write, data.recordComments:read, data.recordComments:write, schema.bases:read).
  5. Connect while signed in to Kody:

https://kody.codes/connect/oauth?provider=airtable&authorizeUrl=https%3A%2F%2Fairtable.com%2Foauth2%2Fv1%2Fauthorize&tokenUrl=https%3A%2F%2Fairtable.com%2Foauth2%2Fv1%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.airtable.com%2Fv0&scopes=data.records%3Aread%20data.records%3Awrite%20data.recordComments%3Aread%20data.recordComments%3Awrite%20schema.bases%3Aread&flow=confidential&pkce=true&tokenExchangeStyle=basic-form&allowedHosts=api.airtable.com&dashboardUrl=https%3A%2F%2Fairtable.com%2Fcreate%2Foauth

  1. Paste the Airtable client id and client secret into the Kody wizard (never into chat). Approve host api.airtable.com.
  2. Reconnect later with https://kody.codes/connect/oauth?provider=airtable

OAuth authorize URL: https://airtable.com/oauth2/v1/authorize. Token URL: https://airtable.com/oauth2/v1/token. Flow: confidential (client secret) plus S256 PKCE. Token exchange style: basic-form. Airtable scopes are space-separated.

To connect a second workspace, change provider (for example provider=airtable-work) and pass integrationName: 'airtable-work' on every call.

Lane B — Personal access token
  1. Create a token at https://airtable.com/create/tokens
  2. Grant the scopes above and add the bases this agent should see.
  3. Save it (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=airtablePat&description=Airtable%20personal%20access%20token&allowedHosts=api.airtable.com&scope=user

For a second workspace/token, use a distinct secret name such as airtablePat-work and pass secretName: 'airtablePat-work' (or account: 'work', which resolves to airtable-work / airtablePat-work).

Scopes
ScopeNeeded for
schema.bases:readlist/get bases and tables
data.records:readlist/get records
data.records:writecreate/update/delete records
data.recordComments:readlist comments
data.recordComments:writecreate comments

viewer and smoke-test call /meta/whoami, which does not require a scope. This package does not request user.email:read.

Agents: see AGENTS.md for import paths, smoke, and dryRun.

Done when

  • The airtable OAuth integration is connected or airtablePat is saved; host api.airtable.com is approved
  • Smoke test returns { ok: true } (live whoami without email when credentials exist, or setup URLs when they do not)
  • Mutations refuse without confirm: true; dryRun: true never calls Airtable

Branding

The community icon is Airtable's official product mark as published at https://airtable.com/images/favicon/mstile-144x144.png (the current isometric logomark). Pixels are unmodified. Airtable® and the Airtable trademark are registered trademarks of Formagrid Inc dba Airtable.

Docs