Figma REST Port

Purpose

This is the reference integration for Harbor http_api Action Model authoring for Figma.

Use it when:

• building Figma actions in Harbor
• extending the Dock / Hub Figma entry
• teaching Codex or OpenClaw how to map a design API into Harbor Ports and Harbor Actions

Harbor Port worksheet

Product

• Product: Figma REST API
• Publisher slug: figma
• Publisher name: Figma
• Category: Design
• Tags: figma, design, files, comments, projects

Safe Harbor Port metadata

• Kind: http_api
• Label: Figma REST API
• Description: Figma REST API connection managed locally through Harbor.
• Base URL: https://api.figma.com/
• Auth mode: header_token
• Auth header name: X-Figma-Token

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Figma is a strong Harbor fit across a much broader fixed-route surface than the original starter set. The current Dock manifest is still the 3-action starter, but the large-API planning pass now maps 45 supportable actions into two implementation phases.

The current Harbor Dock entry assumes a local personal access token sent in X-Figma-Token. Figma OAuth bearer flows also exist, and that auth split matters for GET /v1/me, which is currently deferred until the auth model is widened or split.

Good Harbor Figma actions in the planned full pass:

• stable file inspection routes like /v1/files/{file_key}, /v1/files/{file_key}/nodes, /v1/files/{file_key}/meta, and /v1/files/{file_key}/versions
• bounded collaboration routes like /v1/files/{file_key}/comments and comment reaction endpoints
• fixed project and design-system routes for projects, components, component sets, styles, variables, and dev resources
• organization and library reads like activity logs, discovery, and library analytics
• webhook lifecycle routes with approval and destination policy review

Approval guidance for the planned full pass:

• read-only routes stay automatic
• comment writes, variable mutation, dev-resource writes, and webhook lifecycle actions should be require_approval
• webhook endpoints need explicit operator review because they introduce outbound delivery infrastructure

Current Harbor coverage

Starter actions currently in the manifest

• get-file -> GET /v1/files/{file_key}
• get-comments -> GET /v1/files/{file_key}/comments
• list-team-projects -> GET /v1/teams/{team_id}/projects

Planned full Figma action surface

Phase 1: core design and collaboration

• file inspection: get-file, get-file-nodes, get-images, get-file-images, get-file-meta, get-file-versions
• collaboration: get-comments, create-file-comment, delete-file-comment, list-comment-reactions, create-comment-reaction, delete-comment-reaction
• project and design-library reads: list-team-projects, list-project-files, list-file-components, get-component, list-file-component-sets, get-component-set, list-file-styles, get-style, get-local-variables, get-published-variables
• developer handoff reads: list-file-dev-resources

Phase 2: admin, governance, and analytics

• team-level asset reads: list-team-components, list-team-component-sets, list-team-styles
• state-changing actions: mutate-file-variables, create-dev-resource, update-dev-resource, delete-dev-resource
• webhook lifecycle: create-webhook, get-webhook, list-webhooks, update-webhook, delete-webhook, list-team-webhooks-deprecated, list-webhook-requests
• org and library intelligence: get-activity-logs, get-discovery-text-events, get-library-component-actions, get-library-component-usages, get-library-style-actions, get-library-style-usages, get-library-variable-actions, get-library-variable-usages

Why this API is now treated as large

Figma's officially documented REST surface crosses the 33-action threshold once file inspection, comments, projects, reusable assets, variables, dev resources, webhooks, activity logs, discovery, and library analytics are inventoried together.

That means the current standard requires a planning-first pass before full implementation. The planning artifacts now live alongside the manifest in apps/hub/catalog/integrations/figma/ActionMap.md and apps/hub/catalog/integrations/figma/TechnicalLimitations.md.

Suggested operator workflow

1. Import the Figma Dock entry from Dock / Hub.
2. Configure the local Figma token in Harbor Node.
3. Validate get-file first to confirm local auth and file scope.
4. Use get-comments and list-team-projects only after confirming the token carries the needed scopes.
5. Use the ActionMap phase plan before expanding the manifest because Figma is now tracked as a phased large-API integration.
6. Review OAuth and team-scope caveats before adding GET /v1/me or widening auth assumptions.

Suggested agent workflow

1. Inspect the existing Figma Harbor Port.
2. Inspect live actions and drafts.
3. Use the phase map to keep work under the 33-action implementation threshold per pass.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• widen Figma into a generic arbitrary HTTP proxy
• assume project endpoints work for all OAuth app types without operator review
• assume GET /v1/me fits the current personal-token Harbor auth model without widening or splitting auth behavior

Current update strategy

For now, Figma updates are manual and phased:

• update the Dock / Hub integration document in apps/hub/catalog/integrations/figma/figma-rest-api.json
• update apps/hub/catalog/integrations/figma/ActionMap.md as each implementation phase lands
• update apps/hub/catalog/integrations/figma/TechnicalLimitations.md if new Harbor platform blockers appear
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Figma REST API introduction: https://developers.figma.com/docs/rest-api/
• Figma authentication: https://developers.figma.com/docs/rest-api/authentication/
• Figma file endpoints: https://developers.figma.com/docs/rest-api/file-endpoints/
• Figma comments endpoints: https://developers.figma.com/docs/rest-api/comments-endpoints/
• Figma projects endpoints: https://developers.figma.com/docs/rest-api/projects-endpoints/