Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jottakka merged 2 commits into from
Dec 10, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8129b7d
[TOO-193] Adding Figma Optimized Toolkit Docs
Dec 5, 2025
5e387fd
update after renatos review
Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 65 additions & 41 deletions app/en/home/auth-providers/figma/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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">
Expand Down Expand Up @@ -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
Copy link
Member

@byrro byrro Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it necessary to mention the scopes in two different places? In the future, when this needs to be updated, we risk someone updates the first block of mentions and skip the second. Perhaps we can add a link here referring to the block listing the scopes?

- `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)
Copy link

@cursor cursor bot Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Duplicated scopes list creates maintenance risk (Bugbot Rules)

As noted in the PR discussion by @byrro, the OAuth scopes are listed in two separate locations in this documentation file. The first list appears in "Required scopes for the Figma MCP Server" (lines 27-33) and the second appears in "Set up OAuth configuration" (lines 78-86). If these scopes need to be updated in the future, there's a risk that only one location gets updated, leading to inconsistent documentation. Consider consolidating to a single authoritative list with cross-references.

Additional Locations (1)

Fix in Cursor Fix in Web


For a complete list of available scopes, refer to the [Figma OAuth Scopes documentation](https://developers.figma.com/docs/rest-api/scopes/)

</Steps>

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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":
Expand All @@ -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",
]);

Expand All @@ -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."],
Expand All @@ -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:
Expand All @@ -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/).
1 change: 1 addition & 0 deletions app/en/mcp-servers/development/_meta.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
export default {
e2b: "E2B",
figma: "Figma",
github: "GitHub",
firecrawl: "Firecrawl",
"vercel-api": "Vercel API",
Expand Down
Loading