figma-install-auth

Figma Install & Auth

Overview

Configure authentication for the Figma REST API. Figma supports two auth methods: Personal Access Tokens (PATs) for scripts and server-side tools, and OAuth 2.0 for apps that act on behalf of users. All requests go to https://api.figma.com.

Prerequisites

• Figma account (Free, Professional, or Enterprise)
• Node.js 18+ (for JS/TS integrations)
• A Figma file key (the string after /design/ in a Figma URL)

Instructions

Step 1: Generate a Personal Access Token

1. Open Figma > Settings > Account > Personal access tokens
2. Click Generate new token
3. Name the token and assign scopes:

Scope	Access	Use Case
file_content:read	Read file JSON	Inspecting layers, extracting design tokens
file_content:write	Modify files	Programmatic design updates
file_comments:read	Read comments	Review tooling
file_comments:write	Post comments	Automated feedback
file_dev_resources:read	Dev resources	Dev mode integrations
file_variables:read	Read variables	Design token sync
file_variables:write	Write variables	Token pipeline
webhooks:write	Manage webhooks	Event-driven automation

3. Copy the token immediately -- it is shown only once
4. PATs expire after a maximum of 90 days

Step 2: Store Credentials Securely

# .env (NEVER commit to git)
FIGMA_PAT="figd_your-personal-access-token"
FIGMA_FILE_KEY="abc123XYZdefaultFileKey"

# .gitignore
.env
.env.local
.env.*.local

Step 3: Verify Connection

# Test with curl -- should return your user profile
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  https://api.figma.com/v1/me | jq '.handle, .email'

// verify-figma.ts
const PAT = process.env.FIGMA_PAT!;

const res = await fetch('https://api.figma.com/v1/me', {
  headers: { 'X-Figma-Token': PAT },
});

if (!res.ok) throw new Error(`Figma auth failed: ${res.status}`);
const me = await res.json();
console.log(`Authenticated as ${me.handle} (${me.email})`);

Step 4: OAuth 2.0 (For User-Facing Apps)

Use OAuth when your app needs to act on behalf of other Figma users.

// 1. Redirect user to Figma authorization URL
const authUrl = new URL('https://www.figma.com/oauth');
authUrl.searchParams.set('client_id', process.env.FIGMA_CLIENT_ID!);
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/auth/callback');
authUrl.searchParams.set('scope', 'file_content:read,file_comments:write');
authUrl.searchParams.set('state', crypto.randomUUID());
authUrl.searchParams.set('response_type', 'code');
// Redirect: res.redirect(authUrl.toString());

// 2. Exchange code for access token (must happen within 30 seconds)
async function exchangeCode(code: string): Promise<string> {
  const res = await fetch('https://api.figma.com/v1/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.FIGMA_CLIENT_ID!,
      client_secret: process.env.FIGMA_CLIENT_SECRET!,
      redirect_uri: 'https://yourapp.com/auth/callback',
      code,
      grant_type: 'authorization_code',
    }),
  });
  const { access_token, refresh_token, expires_in } = await res.json();
  // Store refresh_token securely for later use
  return access_token;
}

// 3. Refresh expired tokens
async function refreshToken(refreshToken: string): Promise<string> {
  const res = await fetch('https://api.figma.com/v1/oauth/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.FIGMA_CLIENT_ID!,
      client_secret: process.env.FIGMA_CLIENT_SECRET!,
      refresh_token: refreshToken,
    }),
  });
  const { access_token } = await res.json();
  return access_token;
}

Output

• Personal access token stored in .env
• Successful GET /v1/me returning your user handle
• (Optional) OAuth flow with token exchange working

Error Handling

Error	Status	Cause	Solution
403 Forbidden	403	Token lacks required scope	Regenerate PAT with correct scopes
Invalid token	403	Expired or revoked PAT	Generate a new token (90-day max)
OAuth code expired	400	Code exchange took >30s	Retry auth flow; exchange immediately
Invalid redirect_uri	400	Redirect URL mismatch	Must match URL registered in Figma OAuth app settings
Rate limited	429	Too many auth attempts	Wait for Retry-After header value

Examples

Reusable Figma Client Wrapper

// src/figma-client.ts
export function figmaFetch(path: string, options: RequestInit = {}) {
  const token = process.env.FIGMA_PAT;
  if (!token) throw new Error('FIGMA_PAT environment variable is not set');

  return fetch(`https://api.figma.com${path}`, {
    ...options,
    headers: {
      'X-Figma-Token': token,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
}

// Usage
const file = await figmaFetch(`/v1/files/${fileKey}`).then(r => r.json());

Resources

• Figma REST API Authentication
• Manage Personal Access Tokens
• Figma API Scopes Reference

Next Steps

After successful auth, proceed to figma-hello-world for your first real API call.