Figma connector setup

This page is the setup half — creating the OAuth app Figma needs in its own developer console and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Figma.

1. Create the OAuth app in the Figma developer console

1. Open the Figma developer console and create a new app — this is your own app, not Botseon's. A private app needs no Figma review and works immediately; only a public, listed app needs review, with no published SLA.

2. Under Callback, paste the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

   http://127.0.0.1:3000/api/oauth/figma/callback
   

3. Save. The console shows you a Client ID and a Client secret — copy both now; the secret is shown exactly once.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability). This connector is read-only, so it requests no write scope:

• file_content:read — read a file's document tree.
• file_metadata:read — see a file's name and metadata.
• file_comments:read — read the comments left on a file.
• folders:read — list the files in a folder.

The broad files:read scope is deprecated and extremely permissive; this connector never requests it, and the folder-based scopes above are what the current console offers in its place.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug figma \
  --client-id <the client ID from step 1> \
  --auth-url https://www.figma.com/oauth \
  --token-url https://api.figma.com/v1/oauth/token \
  --configured-by <your user id>

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug figma says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. What this connector does and does not do

This connector is read-only: it has no write tool and raises no approval card.

• figma.get_file — a file's document tree and metadata, by file key.
• figma.get_file_nodes — named nodes from one file, capped at 50 node ids per call.
• figma.list_file_comments — the comments left on a file.
• figma.list_project_files — the files in one folder (the /v2/folders endpoints; the deprecated /v1/projects family is never called).

Figma publishes no separate EU API host: file data is read from api.figma.com, hosted in the US, regardless of where your team is. An authorization code expires in 30 seconds and the access token lasts 90 days.

This connector's catalogue row ships available: false: it stays disabled until the live smoke runs at turn-on.