> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Figma
> Connect Figma to Serval with a personal access token so workflows can read design files, manage comments and webhooks, and call anything in the Figma REST API.
## About Figma
Figma is a collaborative interface-design platform for design files, prototyping, and design systems. Serval connects to Figma with a single personal access token: you paste it in once, Serval stores it encrypted, and every workflow call is sent to Figma with that token attached. The connection acts like the Figma user who created the token - it can see and change whatever that user (and the token's scopes, if any were chosen at creation) can. Serval only ever sends the token to one host for this integration: api.figma.com.
**Authentication:** API key (Figma personal access token)
**Data sync:** On-demand only. There is no background sync, resource import, or scheduled polling - Serval calls Figma only when a workflow runs.
## What the Figma integration enables
| Capability | Description |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read files, nodes, and versions | Fetch a design file's full contents, specific layers within it, file metadata, and version history. |
| Render images and fetch image fills | Generate image renders of file contents (render links expire after 30 days) and retrieve download links for images used as fills (those links expire within 14 days). |
| Manage comments and reactions | List, post, and delete comments on files, and view, add, or remove emoji reactions on them. |
| Browse teams and projects | List a team's projects and the files inside a project. |
| Inspect components and styles | Read published components, component sets, and styles at the team, file, or individual level. |
| Read and modify variables | Read a file's local and published design variables, and create, update, or delete them (Figma makes variables available to full members of Enterprise organizations). |
| Manage webhooks | List, create, update, and delete webhooks - including a team's webhooks - and inspect recent webhook deliveries. |
| Manage dev resources | Read, create, update, and delete a file's dev resources. |
| Pull library analytics | Read action and usage analytics for a library's components, styles, and variables. |
| Read activity logs and payments | Read organization activity logs (Figma reserves these for organization administrators) and payment information for plugins, widgets, and Community files you own. |
| Identity check | Look up which Figma user the stored token belongs to - a quick way to verify the connection. |
Anything defined in the [Figma API](https://www.figma.com/developers/api) can be accessed through Serval.
## Get your credentials
Serval needs a Figma **personal access token**. The token carries the access of the Figma user who creates it - narrowed by any scopes chosen at creation - so generate it as the user whose files, projects, and teams Serval should be able to reach. Figma's official guide is here: [Manage personal access tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens).
Log in as the user whose access you want Serval to use.
Open your Figma account settings and go to the **Personal access tokens** section.
Create a new token and give it a descriptive name (e.g. "Serval Integration"). If Figma asks you to choose an expiration and scopes, remember that Serval can never do more than the token allows: grant the scopes your workflows will need, and note the expiration date - when the token lapses, you'll need to create a new one and update the connection.
Figma shows the token only once. Copy it before closing the dialog.
Figma displays the token a single time. If you navigate away without copying it, you'll need to create a new one.
Serval never requests or narrows scopes itself - the connection can do exactly what the token allows, no more. Many teams create the token from a dedicated service account rather than a personal account.
## Connect in Serval
Add a new Figma connection from your Serval integrations page.
The **Instance Name (optional)** field is described as "A name to distinguish between different Figma workspaces (e.g., 'Design Team', 'Marketing')". It's a label only and doesn't affect access. Leave it blank and the connection is simply named "Figma".
The **Personal Access Token** field is required (marked with an asterisk) and is described as "Your Figma personal access token. Generate this in Account Settings > Personal access tokens".
If installation fails, the form shows "Failed to install integration" along with the underlying error.
When you edit an existing connection, the stored token appears as a masked value - dots plus its last 4 characters - that you can't type into directly. To swap in a new token, click **Replace** (or the pencil icon on the connection settings page) and paste the replacement into the "Enter new value" box. If you change your mind, saving with that box still empty keeps your existing stored token.
## Verifying the connection
Figma connections don't currently include built-in health checks, so you won't see a health-check panel on this connection the way you do for some other integrations. The quickest way to confirm everything works after connecting is to run a workflow step that performs the identity check from the capability table above - asking Figma which user the stored token belongs to. If it returns the expected user's profile, the token is valid and correctly attached.
Serval doesn't rewrite Figma's errors, so a revoked, expired, or mis-pasted token shows up as an authentication error straight from Figma.
A successful identity check only proves the token itself is valid. If it passes but a workflow still fails on a specific file, project, or team, the token's Figma user can't see that resource - or the call is hitting a feature your Figma plan or role doesn't include (see below).
## Gotchas and troubleshooting
The connection has exactly one credential - a personal access token - and Serval never requests or narrows access on top of it. Workflows can reach precisely what the token's Figma user (and the token's scopes, if any were chosen at creation) can reach. If something is invisible to that user in Figma, the call fails in Serval. Fix it by creating a token as a user with the right access - and with sufficient scopes - then replacing the token on the connection.
Figma identifies files by a **file key**, which is the short string of letters and numbers that appears right after "file/" or "design/" in the file's web address - not the full URL. Pasting an entire URL, a node ID, or a project ID where a file key is expected will fail; node, team, and project IDs are separate values.
Several areas of the Figma API are gated by Figma itself, not by Serval: design variables are available to full members of Figma Enterprise organizations, activity logs are reserved for organization administrators, and payments can only be queried for plugins, widgets, and Community files you own. If these calls fail while ordinary file-level calls succeed, the token's account lacks the required Figma plan or role - there's nothing to change on the Serval side.
On the edit form the token appears as a masked value (dots plus its last 4 characters), so it's never shown in full, and the masked field is read-only. Click **Replace** (on the reconnect form) or the pencil icon (on the connection settings page) to get an empty "Enter new value" box, then paste the entire replacement token - whatever you paste is saved exactly as entered. Leaving the field untouched, or saving while the replacement box is still empty, keeps your existing stored token. If an update fails, Serval shows "Failed to update integration" or "Failed to update configuration", depending on which form you used.
The Instance Name field appears when you first connect (and on the reconnect form), but not on the connection's settings page. On an update, entering a new Instance Name replaces the display name, while leaving it blank keeps the current one - there's no way to reset it to the default through the form. Serval also derives an internal instance identifier from the name once, at creation time, and never changes it afterward. Two Figma connections created on the same team with the same Instance Name (or both left blank) end up with identical internal identifiers, so give each connection a distinct name when you create it.
***
Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Figma integration.