Skip to main content

​
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

Anything defined in the Figma 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.
1

Log in to Figma

Log in as the user whose access you want Serval to use.
2

Open the token settings

Open your Figma account settings and go to the Personal access tokens section.
3

Create the token

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.
4

Copy the token immediately

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

1

Open the Figma connect form in Serval

Add a new Figma connection from your Serval integrations page.
2

(Optional) Enter an Instance Name

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”.
3

Paste your Personal Access Token

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”.
4

Save the connection

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 for assistance with your Figma integration.