[TOO-193] Adding Figma Optimized Toolkit Docs (#587)

Author: jottakka

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

@@ -2,11 +2,11 @@ import { Tabs, Callout, Steps } from "nextra/components";
 
 # Figma
 
-The Figma auth provider enables tools and agents to call [Figma APIs](https://www.figma.com/developers/api) on behalf of a user using OAuth 2.0 authentication.
+The Figma auth provider enables tools and agents to call [Figma APIs](https://developers.figma.com/docs/rest-api/) on behalf of a user using OAuth 2.0 authentication.
 
 <Callout>
   Want to quickly get started with Figma in your agent or AI app? The pre-built
-  [Arcade Figma MCP Server](/mcp-servers/productivity/figma-api) is what you
+  [Arcade Figma MCP Server](/mcp-servers/development/figma) is what you
   want!
 </Callout>
 
@@ -16,10 +16,28 @@ This page describes how to use and configure Figma auth with Arcade.
 
 This auth provider is used by:
 
-- The [Arcade Figma MCP Server](/mcp-servers/productivity/figma-api), which provides pre-built tools for interacting with Figma
+- The [Arcade Figma MCP Server](/mcp-servers/development/figma), which provides pre-built tools for interacting with Figma
 - Your [app code](#using-figma-auth-in-app-code) that needs to call the Figma API
 - Or, your [custom tools](#using-figma-auth-in-custom-tools) that need to call the Figma API
 
+### Required scopes for the Figma MCP Server
+
+If you're using the [Arcade Figma MCP Server](/mcp-servers/development/figma), you'll need to configure these scopes based on which tools you plan to use:
+
+- `file_content:read` - File structure, pages, nodes, and image exports
+- `library_content:read` - Published components, styles, and component sets from files
+- `team_library_content:read` - Team library content
+- `library_assets:read` - Individual component, style, and component set metadata
+- `file_comments:read` / `file_comments:write` - Reading and creating comments
+- `current_user:read` - User profile information
+- `projects:read` - Team projects and files (**requires private OAuth app**)
+
+<Callout type="warning">
+The `projects:read` scope is **only available in private Figma OAuth apps**. If you need to access team projects and files, you must create a private OAuth app through your Figma organization.
+</Callout>
+
+For detailed descriptions of all available Figma OAuth scopes, refer to the [Figma OAuth Scopes documentation](https://developers.figma.com/docs/rest-api/scopes/).
+
 ## Configuring Figma auth
 
 <Callout type="info">
@@ -57,10 +75,17 @@ Navigate to the [Figma Developer Portal](https://www.figma.com/developers/) and
 
 1. After creating your app, you'll receive a `client_id` and `client_secret`
 2. Set the redirect URI to the redirect URL generated by Arcade (see configuration section below)
-3. Configure the required scopes for your application:
-   - `files:read` - Read access to files
+3. Configure the required scopes for your application based on the tools you need:
+   - `file_content:read` - Read access to file content and structure
+   - `library_content:read` - Read access to published library content
+   - `team_library_content:read` - Read access to team library content
+   - `library_assets:read` - Read access to individual library assets
+   - `file_comments:read` - Read access to file comments
    - `file_comments:write` - Write access to file comments
-   - Add other scopes as needed for your use case
+   - `current_user:read` - Read access to user profile
+   - `projects:read` - Read access to team projects (private apps only)
+   
+For a complete list of available scopes, refer to the [Figma OAuth Scopes documentation](https://developers.figma.com/docs/rest-api/scopes/)
 
 </Steps>
 
@@ -89,12 +114,14 @@ To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://a
 
 #### Enter the provider details
 
-- Choose a unique **ID** for your provider (e.g. "arcade-figma").
+- Choose a unique **ID** for your provider (e.g. "figma").
 - Optionally enter a **Description**.
 - Enter the **Client ID** and **Client Secret** from your Figma app.
 - Configure the OAuth 2.0 endpoints:
   - **Authorization URL**: `https://www.figma.com/oauth`
-  - **Token URL**: `https://www.figma.com/api/oauth/token`
+  - **Token URL**: `https://api.figma.com/v1/oauth/token`
+  - **Scope Delimiter**: ` ` (space)
+  - **Use PKCE**: Enabled (S256)
 - Note the **Redirect URL** generated by Arcade. This must be set as your Figma app's redirect URI.
 
 #### Create the provider
@@ -139,33 +166,46 @@ Edit the `engine.yaml` file and add a new item to the `auth.providers` section:
 ```yaml
 auth:
   providers:
-    - id: arcade-figma
+    - id: figma
       description: Figma OAuth 2.0 provider
       enabled: true
       type: oauth2
       client_id: ${env:FIGMA_CLIENT_ID}
       client_secret: ${env:FIGMA_CLIENT_SECRET}
       oauth2:
-        scope_delimiter: ","
+        scope_delimiter: " "
+        use_pkce: true
+        pkce_code_challenge_method: S256
         authorize_request:
           endpoint: "https://www.figma.com/oauth"
           params:
             response_type: code
             client_id: "{{client_id}}"
             redirect_uri: "{{redirect_uri}}"
-            scope: "{{scopes}}"
+            scope: "{{scopes}} {{existing_scopes}}"
             state: "{{state}}"
         token_request:
-          endpoint: "https://www.figma.com/api/oauth/token"
+          endpoint: "https://api.figma.com/v1/oauth/token"
           auth_method: client_secret_basic
           params:
             grant_type: authorization_code
-            client_id: "{{client_id}}"
-            client_secret: "{{client_secret}}"
             redirect_uri: "{{redirect_uri}}"
+          request_content_type: application/x-www-form-urlencoded
+          response_content_type: application/json
+        refresh_request:
+          endpoint: "https://api.figma.com/v1/oauth/token"
+          auth_method: client_secret_basic
+          params:
+            grant_type: refresh_token
+            refresh_token: "{{refresh_token}}"
+          request_content_type: application/x-www-form-urlencoded
           response_content_type: application/json
 ```
 
+<Callout type="warning">
+**Note on `projects:read` scope:** If you need access to the `projects:read` scope for team projects and files navigation, you must create a **private Figma OAuth app**. This scope is not available in public OAuth apps. Learn more in the [Figma OAuth Scopes documentation](https://developers.figma.com/docs/rest-api/scopes/).
+</Callout>
+
 </Steps>
 
 </Tabs.Tab>
@@ -192,8 +232,8 @@ user_id = "{arcade_user_id}"
 # Start the authorization process
 auth_response = client.auth.start(
     user_id=user_id,
-    provider="arcade-figma",
-    scopes=["files:read", "file_comments:write"]
+    provider="figma",
+    scopes=["file_content:read", "file_comments:write"]
 )
 
 if auth_response.status != "completed":
@@ -219,8 +259,8 @@ const client = new Arcade();
 const userId = "{arcade_user_id}";
 
 // Start the authorization process
-const authResponse = await client.auth.start(userId, "arcade-figma", [
-  "files:read",
+const authResponse = await client.auth.start(userId, "figma", [
+  "file_content:read",
   "file_comments:write",
 ]);
 
@@ -242,26 +282,21 @@ const token = authResponse.context.token;
 
 ## Using Figma auth in custom tools
 
-You can use the pre-built [Arcade Figma MCP Server](/mcp-servers/productivity/figma-api) to quickly build agents and AI apps that interact with Figma.
+You can use the pre-built [Arcade Figma MCP Server](/mcp-servers/development/figma) to quickly build agents and AI apps that interact with Figma.
 
 If the pre-built tools in the Figma 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 Figma API.
 
-Use the `OAuth2()` auth class to specify that a tool requires authorization with Figma. The `context.authorization.token` field will be automatically populated with the user's Figma token:
+Use the `Figma()` auth class to specify that a tool requires authorization with Figma. The `context.authorization.token` field will be automatically populated with the user's Figma token:
 
-```python {8-12,22}
+```python {5,8}
 from typing import Annotated
 
 import httpx
 from arcade_tdk import ToolContext, tool
-from arcade_tdk.auth import OAuth2
+from arcade_tdk.auth import Figma
 
 
-@tool(
-    requires_auth=OAuth2(
-        provider_id="arcade-figma",
-        scopes=["files:read"]
-    )
-)
+@tool(requires_auth=Figma(scopes=["file_content:read"]))
 async def get_figma_file(
     context: ToolContext,
     file_key: Annotated[str, "The Figma file key to retrieve."],
@@ -271,7 +306,7 @@ async def get_figma_file(
     """
     url = f"https://api.figma.com/v1/files/{file_key}"
     headers = {
-        "Authorization": context.authorization.token,
+        "Authorization": f"Bearer {context.authorization.token}",
     }
 
     async with httpx.AsyncClient() as client:
@@ -280,15 +315,4 @@ async def get_figma_file(
         return dict(response.json())
 ```
 
-## Available Scopes
-
-Figma supports various OAuth scopes that determine the level of access your application has:
-
-- `files:read` - Read access to files
-- `file_comments:write` - Write access to file comments
-- `file_dev_resources:write` - Write access to dev resources
-- `file_variables:read` - Read access to variables
-- `file_variables:write` - Write access to variables
-- `webhooks:write` - Write access to webhooks
-
-For a complete list of available scopes and their descriptions, refer to the [Figma API documentation](https://www.figma.com/developers/api#authentication).
+For a complete list of available Figma OAuth scopes and their descriptions, refer to the [Figma OAuth Scopes documentation](https://developers.figma.com/docs/rest-api/scopes/).

app/en/mcp-servers/development/_meta.tsx

@@ -1,5 +1,6 @@
 export default {
   e2b: "E2B",
+  figma: "Figma",
   github: "GitHub",
   firecrawl: "Firecrawl",
   "vercel-api": "Vercel API",