import { Tabs, Callout, Steps } from "nextra/components"; # Figma 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. Want to quickly get started with Figma in your agent or AI app? The pre-built [Arcade Figma MCP Server](/resources/integrations/development/figma) is what you want! ### What's documented here This page describes how to use and configure Figma auth with Arcade. This auth provider is used by: - The [Arcade Figma MCP Server](/resources/integrations/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](/resources/integrations/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**) 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. 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 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. In a production environment, you will most likely want to use your own Figma app credentials. This way, your users will see your application's name requesting permission. Before showing how to configure your Figma app credentials, let's go through the steps to create a Figma app. ### Create a Figma app To integrate with Figma's API, you'll need to set up OAuth 2.0 authentication by creating an app in the Figma Developer Portal: #### Access the Figma Developer Portal Navigate to the [Figma Developer Portal](https://www.figma.com/developers/) and sign in with your existing Figma credentials or create a new account. #### Create a new app 1. Once logged in, go to your developer dashboard and select "My Apps" 2. Click on "Create a new app" 3. Fill in the required details: - **App Name**: Choose a descriptive name for your application - **Website**: Provide the URL of your application's website - **App Logo**: Upload a 100x100px PNG image representing your app #### Set up OAuth configuration 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 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 - `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/) For detailed instructions, refer to Figma's official [Authentication documentation](https://developers.figma.com/docs/rest-api/authentication/). Next, add the Figma app to Arcade. ## Configuring your own Figma Auth Provider in Arcade ### Configure Figma Auth Using the Arcade Dashboard GUI #### 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 **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. - 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. "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://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 Hit the **Create** button and the provider will be ready to be used. ### Configure Figma Auth Using Configuration File This method is only available when you are [self-hosting the engine](/guides/deployment-hosting/on-prem #### Set environment variables Set the following environment variables: ```bash export FIGMA_CLIENT_ID="" export FIGMA_CLIENT_SECRET="" ``` Or, you can set these values in a `.env` file: ```bash FIGMA_CLIENT_ID="" FIGMA_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: 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: " " 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}} {{existing_scopes}}" state: "{{state}}" token_request: endpoint: "https://api.figma.com/v1/oauth/token" auth_method: client_secret_basic params: grant_type: authorization_code 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 ``` **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/). When you use tools that require Figma auth using your Arcade account credentials, Arcade will automatically use this Figma OAuth provider. If you have multiple Figma providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information. ## Using Figma auth in app code Use the Figma auth provider in your own agents and AI apps to get a user token for the Figma 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 Figma API: ```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="figma", scopes=["file_content:read", "file_comments: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) token = auth_response.context.token # Do something interesting with the token... ``` ```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, "figma", [ "file_content:read", "file_comments: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 authResponse = await client.auth.waitForCompletion(authResponse); const token = authResponse.context.token; // Do something interesting with the token... ``` ## Using Figma auth in custom tools You can use the pre-built [Arcade Figma MCP Server](/resources/integrations/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](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Figma API. 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 {5,8} from typing import Annotated import httpx from arcade_tdk import ToolContext, tool from arcade_tdk.auth import Figma @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."], ) -> Annotated[dict, "The Figma file data."]: """ Retrieve a Figma file by its key. """ url = f"https://api.figma.com/v1/files/{file_key}" headers = { "Authorization": f"Bearer {context.authorization.token}", } async with httpx.AsyncClient() as client: response = await client.get(url, headers=headers) response.raise_for_status() return dict(response.json()) ``` 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/).