Figma Upgrade & Migration
Overview
Handle Figma REST API deprecations and breaking changes. The most significant recent change is the deprecation of the files:read scope in favor of granular scopes, and the move from Webhooks V1 to V2.
Prerequisites
- Current Figma integration working
- Git for version control
- Access to Figma developer settings
Instructions
Step 1: Scope Migration (files:read Deprecation)
The files:read scope is deprecated. Migrate to granular scopes:
| Deprecated Scope | Replacement Scopes | Endpoints Covered |
|---|
files:read | file_content:read | GET /v1/files/:key, GET /v1/images/:key |
files:read | file_comments:read | GET /v1/files/:key/comments |
files:read | file_dev_resources:read | GET /v1/files/:key/dev_resources |
files:read | file_versions:read | GET /v1/files/:key/versions |
Migration steps:
- Audit which endpoints your code calls
- Map each endpoint to its required scope
- Generate a new PAT with granular scopes
- Update OAuth apps with new scope list
- Test all endpoints with the new token
- Revoke old tokens
grep -rn "api.figma.com" --include="*.ts" --include="*.js" src/ \
| grep -oP '/v\d/[a-z_/]+' | sort -u
Step 2: Webhooks V1 to V2 Migration
interface WebhookV2Config {
event_type: 'FILE_UPDATE' | 'FILE_DELETE' | 'FILE_VERSION_UPDATE'
| 'FILE_COMMENT' | 'LIBRARY_PUBLISH';
team_id?: string;
endpoint: string;
passcode: string;
description?: string;
}
async function createWebhook(config: WebhookV2Config) {
const res = await fetch('https://api.figma.com/v2/webhooks', {
method: 'POST',
headers: {
'X-Figma-Token': process.env.FIGMA_PAT!,
'Content-Type': 'application/json',
},
body: JSON.stringify(config),
});
if (!res.) ();
res.();
}
() {
res = (
,
{ : { : process..! } }
);
res.();
}
Step 3: OAuth App Publishing Flow
All OAuth apps (public and private) must complete the new publishing flow:
- Go to your app in the Figma developer dashboard
- Complete the required app information fields
- Add required redirect URLs
- Submit for review (public apps) or activate (private apps)
- Update your code to handle the new token format
async function checkTokenHealth(accessToken: string): Promise<boolean> {
const res = await fetch('https://api.figma.com/v1/me', {
headers: { 'X-Figma-Token': accessToken },
});
if (res.status === 403) {
console.warn('Token expired or revoked -- refresh needed');
return false;
}
return res.ok;
}
Step 4: Audit and Update Codebase
function auditFigmaIntegration(codebasePaths: string[]) {
const issues: string[] = [];
const patterns = [
{ pattern: 'files:read', message: 'Deprecated scope: use file_content:read' },
{ pattern: '/v1/webhooks', message: 'V1 webhooks: migrate to /v2/webhooks' },
{ pattern: 'X-FIGMA-TOKEN', message: 'Header is case-sensitive: use X-Figma-Token' },
];
return { issues, patterns };
}
Output
- Scopes migrated from
files:read to granular alternatives
- Webhooks upgraded from V1 to V2
- OAuth app publishing flow completed
- All endpoints tested with new tokens
Error Handling
| Issue | Cause | Solution |
|---|
| 403 after scope change | Missing required scope | Add the specific scope for each endpoint |
| Webhook not firing | V1 webhook still active | Delete V1, create V2 webhook |
| OAuth flow broken | Publishing flow not completed | Complete app publishing in dashboard |
| Token format mismatch | Old token type | Generate new PAT with figd_ prefix |
Examples
Find every deprecated files:read scope reference before Figma sunsets it (Step 1 + Step 4 audit):
/usr/bin/grep -rn "files:read" --include='*.{ts,js,json,yml}' . | /usr/bin/grep -v node_modules
src/auth/oauth.ts:12: scope: 'files:read', ← replace with file_content:read
config/figma-app.json:8: "scopes": ["files:read"] ← update in the Figma app config too
Migrate a V1 webhook to V2 and confirm the new shape (Step 2):
curl -s -X POST https://api.figma.com/v2/webhooks \
-H "X-Figma-Token: ${FIGMA_PAT}" -H 'Content-Type: application/json' \
-d '{"event_type":"FILE_UPDATE","team_id":"'"${FIGMA_TEAM_ID}"'","endpoint":"https://example.com/figma/webhook","passcode":"'"${WEBHOOK_PASSCODE}"'"}' \
| jq '{id, event_type, status}'
Full deprecation table and OAuth publishing steps: references/scope-migration-files-read-deprecation.md, references/oauth-app-publishing-flow.md.
Resources
Next Steps
For CI integration during upgrades, see figma-ci-integration.
