DesignVaultDocs

Figma integration

Three ways to send from Figma to DesignVault, ordered by how often you'll use them.

1. Import via URL (recommended)

The simplest: copy a Figma frame URL, paste it into the Import Asset modal. Works for any file accessible with your token (PAT or OAuth).

We support /file/, /design/ and /proto/ URL formats, with or without the node-id query param. If node-id is missing, we take the first frame of the first page.

2. Figma plugin

The official DesignVault plugin lets you batch-upload several frames without leaving Figma — metadata once, one asset per frame, duplicates detected server-side. Ideal for designers producing at volume.

Authentication uses an OAuth device-flow: the plugin opens a DesignVault approval page in your browser, an owner/admin approves the pairing code, and the plugin receives a dedicated API key. No need to copy-paste your Figma token. Full walkthrough on the Figma plugin page.

3. Programmatic via API

For automations (Zapier, CI scripts, nightly exports), use the POST /api/v1/assets endpoint with a source_url pointing at the Figma frame. The server does the equivalent of a manual import but without a login.

Figma token — PAT vs OAuth

Personal Access Token (PAT)

  • Easiest to set up (one click in Figma → Settings → Security → Personal access tokens)
  • Grants access to everything you can see as a user
  • Recommended for solos and small teams

Scopes to check when generating the token

  • current_user:read + file_content:read — required: token validation, asset import, thumbnail rendering and refresh
  • webhooks:read + webhooks:write — Figma auto-sync (thumbnail refresh on FILE_UPDATE)
  • library_content:read — library sync (auto-import of published components on LIBRARY_PUBLISH)

Nothing else is needed. Figma caps token lifetime at 90 days — plan a renewal reminder; imports and syncs stop silently when the token expires.

OAuth

  • Cleaner: limited scope, revocable from Figma
  • Works at the workspace level (useful if the Figma org has a strict policy)
  • Coming soon — we currently support PAT only

Token security

The token is encrypted with AES-256-GCM before storage using a server key (ENCRYPTION_KEY, 32 bytes hex). Never logged, never returned to the client once entered. If you change tokens, the previous one is overwritten immediately.

Figma rate limits

The Figma API has a global per-account limit (~5,000 reads/min). Our own limits are tighter (30 imports/min/user via the Upstash expensive bucket) to avoid draining your Figma quota. If you get a 429, we retry with exponential backoff (1s, 2s, 4s).

Thumbnail refresh

Two mechanisms keep thumbnails current, no manual action needed:

  • On view — opening the detail view of a Figma asset compares Figma's last_modified with the one we stored. If Figma has a newer version, we re-fetch the PNG in the background and update the thumbnail.
  • On edit (webhooks) — under Settings → Figma, an owner/admin can register a Figma webhook on a team, project, or file. When a designer edits a file, Figma notifies us (about 30 minutes after the last change) and every asset from that file refreshes — even ones nobody has opened. Requires the webhooks scope on your Figma token.

Library sync

With a webhook registered, publishing a Figma library syncs its components into DesignVault: new published components are imported as component assets (with a deep link back to the exact node), already-imported ones get their name and thumbnail refreshed. Unpublished components are never deleted — they stay as references. Imports respect your plan's asset limit; large libraries converge over successive publishes (60 components per run).