import { Tabs, Callout, Steps } from "nextra/components";

# Airtable

The Airtable auth provider enables tools and agents to call [Airtable APIs](https://airtable.com/developers/web/api/introduction) on behalf of a user using OAuth 2.0 authentication.

<Callout>
  Want to quickly get started with Airtable in your agent or AI app? The
  pre-built [Arcade Airtable MCP
  Server](/resources/integrations/productivity/airtable-api) is what you want!
</Callout>

### What's documented here

This page describes how to use and configure Airtable auth with Arcade.

This auth provider is used by:

- The [Arcade Airtable MCP Server](/resources/integrations/productivity/airtable-api), which provides pre-built tools for interacting with Airtable
- Your [app code](#using-airtable-auth-in-app-code) that needs to call the Airtable API
- Or, your [custom tools](#using-airtable-auth-in-custom-tools) that need to call the Airtable API

## Configuring Airtable auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own Airtable app credentials. This way, your users will see your application's name requesting permission.

Before showing how to configure your Airtable app credentials, let's go through the steps to create an Airtable app.

### Create an Airtable app

To integrate with Airtable's API, you'll need to create an OAuth integration:

<Steps>

#### Access the Airtable Developer Hub

Navigate to the [Airtable Developer Hub](https://airtable.com/developers/web) and sign in with your Airtable account.

#### Create a new OAuth integration

1. Go to the [Create OAuth Integration](https://airtable.com/create/oauth) page
2. Fill in the required details:
   - **Integration Name**: Choose a descriptive name for your application
   - **Description**: Provide a brief description of your app's purpose

#### Configure OAuth settings

1. Set the **Redirect URL** to the redirect URL generated by Arcade (see configuration section below)
2. Configure the required **Scopes** for your application:
   - `data.records:read` - Read records from tables
   - `data.records:write` - Create, update, and delete records
   - `schema.bases:read` - Read base schema
   - Add other scopes as needed for your use case

#### Obtain your credentials

1. After creating your integration, you'll receive a **Client ID**
2. Generate a **Client Secret** from your integration settings
3. Copy both values for use in Arcade configuration

</Steps>

For detailed instructions, refer to Airtable's [OAuth documentation](https://airtable.com/developers/web/guides/oauth-integrations).

Next, add the Airtable app to Arcade.

## Configuring your own Airtable Auth Provider in Arcade

<Tabs items={["Dashboard GUI", "Configuration File"]}>
<Tabs.Tab>

### Configure Airtable Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **OAuth** section of the Arcade Dashboard left-side menu, click **Providers**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **OAuth 2.0** tab at the top.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "arcade-airtable").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your Airtable integration.
- Configure the OAuth 2.0 endpoints:
  - **Authorization URL**: `https://airtable.com/oauth2/v1/authorize`
  - **Token URL**: `https://airtable.com/oauth2/v1/token`
- Note the **Redirect URL** generated by Arcade. This must be set as your Airtable integration's Redirect URL.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

</Tabs.Tab>

<Tabs.Tab>

### Configure Airtable Auth Using Configuration File

<Callout type="info">
  This method is only available when you are [self-hosting the
  engine](/guides/deployment-hosting/on-prem)
</Callout>

<Steps>

#### Set environment variables

Set the following environment variables:

```bash
export AIRTABLE_CLIENT_ID="<your client ID>"
export AIRTABLE_CLIENT_SECRET="<your client secret>"
```

Or, you can set these values in a `.env` file:

```bash
AIRTABLE_CLIENT_ID="<your client ID>"
AIRTABLE_CLIENT_SECRET="<your client secret>"
```

#### Edit the Engine configuration

Edit the `engine.yaml` file and add a new item to the `auth.providers` section:

```yaml
auth:
  providers:
    - id: arcade-airtable
      description: Airtable OAuth 2.0 provider
      enabled: true
      type: oauth2
      client_id: ${env:AIRTABLE_CLIENT_ID}
      client_secret: ${env:AIRTABLE_CLIENT_SECRET}
      oauth2:
        scope_delimiter: " "
        pkce:
          enabled: true
          code_challenge_method: S256
        authorize_request:
          endpoint: "https://airtable.com/oauth2/v1/authorize"
          params:
            response_type: code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
            scope: "{{scopes}}"
            state: "{{state}}"
        token_request:
          endpoint: "https://airtable.com/oauth2/v1/token"
          params:
            grant_type: authorization_code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
          response_content_type: application/json
```

</Steps>

</Tabs.Tab>
</Tabs>

When you use tools that require Airtable auth using your Arcade account credentials, Arcade will automatically use this Airtable OAuth provider. If you have multiple Airtable providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

## Using Airtable auth in app code

Use the Airtable auth provider in your own agents and AI apps to get a user token for the Airtable API. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for the Airtable API:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {8-12}
from arcadepy import Arcade

client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable

user_id = "{arcade_user_id}"

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="arcade-airtable",
    scopes=["data.records:read", "data.records:write", "schema.bases:read"]
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token
# Do something interesting with the token...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-11}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade();

const userId = "{arcade_user_id}";

// Start the authorization process
const authResponse = await client.auth.start(userId, "arcade-airtable", [
  "data.records:read",
  "data.records:write",
  "schema.bases:read",
]);

if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}

// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);

const token = authResponse.context.token;
// Do something interesting with the token...
```

</Tabs.Tab>

</Tabs>

## Using Airtable auth in custom tools

You can use the pre-built [Arcade Airtable MCP Server](/resources/integrations/productivity/airtable-api) to quickly build agents and AI apps that interact with Airtable.

If the pre-built tools in the Airtable MCP Server don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Airtable API.

Use the `OAuth2()` auth class to specify that a tool requires authorization with Airtable. The `context.authorization.token` field will be automatically populated with the user's Airtable token:

```python {8-12,22}
from typing import Annotated

import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import OAuth2


@tool(
    requires_auth=OAuth2(
        provider_id="arcade-airtable",
        scopes=["data.records:read", "schema.bases:read"]
    )
)
async def list_bases(
    context: ToolContext,
) -> Annotated[dict, "The user's bases."]:
    """
    Retrieve the list of bases accessible to the authenticated user.
    """
    url = "https://api.airtable.com/v0/meta/bases"
    headers = {
        "Authorization": context.authorization.token,
    }

    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return dict(response.json())
```

## Available Scopes

Airtable supports various OAuth scopes that determine the level of access your application has:

- `data.records:read` - Read records from tables
- `data.records:write` - Create, update, and delete records
- `data.recordComments:read` - Read comments on records
- `data.recordComments:write` - Create and update comments on records
- `schema.bases:read` - Read base schema information
- `schema.bases:write` - Modify base schema
- `webhook:manage` - Create and manage webhooks
- `user.email:read` - Read user email address

For a complete list of available scopes, refer to the [Airtable Scopes documentation](https://airtable.com/developers/web/api/scopes).