ArcadeAI
diff --git a/‎app/en/home/auth-providers/airtable/page.mdx‎
Lines changed: 302 additions & 0 deletions b/‎app/en/home/auth-providers/airtable/page.mdx‎
Lines changed: 302 additions & 0 deletions
@@ -0,0 +1,302 @@
+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](/mcp-servers/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](/mcp-servers/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](/home/auth/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](/home/deployment/on-prem-mcp)
+</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](/home/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](/home/auth/how-arcade-helps) 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](/mcp-servers/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](/home/build-tools/create-a-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).
+