[MOAR][Auth Docs] Many providers

app/en/home/auth-providers/airtable/page.mdx

@@ -0,0 +1,270 @@
+import { Tabs, Callout, Steps } from "nextra/components";
+
+# Airtable
+
+The Airtable auth provider enables tools and agents to call Airtable APIs on behalf of a user.
+
+## What's documented here
+
+This page describes how to use and configure Airtable auth with Arcade.
+
+This auth provider is used by:
+
+- Your [app code](#using-airtable-auth-in-app-code) that needs to call Airtable APIs
+- Or, your [custom tools](#using-airtable-auth-in-custom-tools) that need to call Airtable APIs
+
+## Use Arcade's Default Airtable Auth Provider
+
+Arcade offers a default Airtable auth provider that you can use in the Arcade Cloud Platform. In this case, your users will see `Arcade` as the name of the application that's requesting permission.
+
+If you choose to use Arcade's Airtable auth, you don't need to configure anything.
+
+## Use Your Own Airtable App Credentials
+
+<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
+
+Follow the documentation on [Airtable Web API](https://airtable.com/developers/web/api/introduction). You will need to create an OAuth integration in your Airtable account.
+
+When creating your app, use the following settings:
+
+- Set an appropriate App name and description. This will be visible to your users authorizing access to your app.
+- In the **OAuth Settings** section:
+  - Take note of the **Client ID** and **Client Secret**.
+  - Add the redirect URL generated by Arcade (see below) to the **Redirect URLs**.
+- Configure the appropriate **Scopes** for your application. Common scopes include:
+  - `data.records:read` - Read records from bases
+  - `data.records:write` - Create and update records in bases
+  - `schema.bases:read` - Read base schemas
+  - `schema.bases:write` - Modify base schemas
+
+## Configuring your own Airtable Auth Provider in Arcade
+
+<Tabs items={["Dashboard GUI"]}>
+<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 **Included Providers** tab at the top.
+- In the **Provider** dropdown, select **Airtable**.
+
+#### Enter the provider details
+
+- Choose a unique **ID** for your provider (e.g. "my-airtable-provider").
+- Optionally enter a **Description**.
+- Enter the **Client ID** and **Client Secret** from your Airtable OAuth integration.
+- Note the **Redirect URL** generated by Arcade. This must be added to your Airtable OAuth integration's Redirect URLs.
+
+#### Create the provider
+
+Hit the **Create** button and the provider will be ready to be used.
+
+</Steps>
+
+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.
+
+</Tabs.Tab>
+</Tabs>
+
+## Using Airtable auth in app code
+
+Use the Airtable auth provider in your own agents and AI apps to get a user-scoped 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"]}>
+<Tabs.Tab>
+
+```python {21-22}
+from arcadepy import Arcade
+
+client = Arcade(base_url="https://api.arcade.dev")  # 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="airtable",
+    scopes=["data.records:read", "data.records:write"],
+)
+
+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)
+
+# Do something interesting with the token...
+auth_token = auth_response.context.token
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```javascript {20-21}
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade({ baseURL: "https://api.arcade.dev" }); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const userId = "{arcade_user_id}";
+
+// Start the authorization process
+const authResponse = await client.auth.start(userId, "airtable", {
+  scopes: ["data.records:read", "data.records:write"],
+});
+
+if (authResponse.status !== "completed") {
+  console.log("Please complete the authorization challenge in your browser:");
+  console.log(authResponse.url);
+}
+
+// Wait for the authorization to complete
+const response = await client.auth.waitForCompletion(authResponse);
+
+// Do something interesting with the token...
+const auth_token = response.context.token;
+```
+
+</Tabs.Tab>
+</Tabs>
+
+You can use the auth token to call the [Airtable Web API](https://airtable.com/developers/web/api/introduction) endpoints to interact with bases, tables, and records.
+
+## Using Airtable auth in custom tools
+
+You can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with Airtable API.
+
+Use the `OAuth2()` auth class to specify that a tool requires authorization with Airtable. The authentication token needed to call the Airtable API is available in the tool context through the `context.authorization.token` property.
+
+```python {9,17}
+from typing import Annotated
+
+import httpx
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import OAuth2
+
+
+@tool(requires_auth=OAuth2(provider_id="airtable", scopes=["data.records:read"]))
+async def list_records(
+    context: ToolContext,
+    base_id: Annotated[str, "The ID of the base."],
+    table_id: Annotated[str, "The ID or name of the table."],
+) -> Annotated[dict, "List of records"]:
+    """Retrieves records from an Airtable table."""
+    url = f"https://api.airtable.com/v0/{base_id}/{table_id}"
+    headers = {
+        "Authorization": f"Bearer {context.authorization.token}",
+        "Accept": "application/json",
+    }
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, headers=headers)
+        response.raise_for_status()
+        return response.json()
+```
+
+Your new tool can be called like demonstrated below:
+
+<Tabs items={["Python", "JavaScript"]}>
+<Tabs.Tab>
+<Callout type="info">
+  If you are self-hosting, change the `base_url` parameter in the `Arcade` constructor to match your Arcade Engine URL. By default, the Engine will be available at `http://localhost:9099`.
+</Callout>
+
+```python
+from arcadepy import Arcade
+
+client = Arcade(base_url="https://api.arcade.dev")  # Automatically finds the `ARCADE_API_KEY` env variable
+
+USER_ID = "{arcade_user_id}"
+TOOL_NAME = "Airtable.ListRecords"
+
+auth_response = client.tools.authorize(tool_name=TOOL_NAME, user_id=USER_ID)
+
+if auth_response.status != "completed":
+    print(f"Click this link to authorize: {auth_response.url}")
+
+# Wait for the authorization to complete
+client.auth.wait_for_completion(auth_response)
+
+tool_input = {
+    "base_id": "appXXXXXXXXXXXXXX",
+    "table_id": "tblXXXXXXXXXXXXXX",
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=USER_ID,
+)
+print(response.output.value)
+```
+
+</Tabs.Tab>
+<Tabs.Tab>
+<Callout type="info">
+  If you are self-hosting, change the `baseURL` parameter in the `Arcade` constructor to match your Arcade Engine URL. By default, the Engine will be available at `http://localhost:9099`.
+</Callout>
+
+```javascript
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade({ baseURL: "https://api.arcade.dev" }); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "{arcade_user_id}";
+const TOOL_NAME = "Airtable.ListRecords";
+
+// Start the authorization process
+const authResponse = await client.tools.authorize({
+  tool_name: TOOL_NAME,
+  user_id: USER_ID,
+});
+
+if (authResponse.status !== "completed") {
+  console.log(`Click this link to authorize: ${authResponse.url}`);
+}
+
+// Wait for the authorization to complete
+await client.auth.waitForCompletion(authResponse);
+
+const toolInput = {
+  base_id: "appXXXXXXXXXXXXXX",
+  table_id: "tblXXXXXXXXXXXXXX",
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(response.output.value);
+```
+
+</Tabs.Tab>
+</Tabs>