Authentication

Open Figma > Account Settings > Personal Access Tokens and click Create a new personal access token.

Give the token a descriptive name (for example, ci-design-token-sync) and choose an expiration period. Copy the token immediately -- Figma will not show it again.

When creating a token, select only the scopes your application needs. Using the minimum required scopes reduces the impact if a token is compromised.

| Scope | Access granted | |-------|---------------| | file_content:read | Read file data, nodes, and export images | | file_content:write | Write to files (variables, components) | | file_comments:write | Create, edit, and delete comments | | webhooks:write | Create and manage webhook subscriptions | | file_dev_resources:read | Read dev resources from files | | file_dev_resources:write | Write dev resources to files |

Include the token in the X-Figma-Token header on every request.

curl -H "X-Figma-Token: figd_YOUR_TOKEN" \
  "https://api.figma.com/v1/me"

The simplest way to confirm your token is valid is to call the /v1/me endpoint. A 200 response with your user profile means authentication is working.

{
  "id": "12345",
  "handle": "designer",
  "email": "designer@example.com",
  "img_url": "https://s3-alpha.figma.com/img/..."
}

If you receive a 403 Forbidden response, the token is invalid, expired, or lacks the required scope for the endpoint you are calling.

Go to the Figma Developer Portal and create a new application. You will receive a client ID and client secret.

Configure your redirect URI -- this is where Figma sends users after they authorize your app.

Send users to the Figma authorization URL to request access. Include the scopes your application needs.

https://www.figma.com/oauth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=files:read
  &state=RANDOM_STATE_VALUE
  &response_type=code

| Parameter | Required | Description | |-----------|----------|-------------| | client_id | Yes | Your application's client ID | | redirect_uri | Yes | Must match a registered redirect URI | | scope | Yes | Space-separated list of scopes | | state | Yes | A random string to prevent CSRF attacks | | response_type | Yes | Must be code |

Available OAuth scopes:

| Scope | Access granted | |-------|---------------| | files:read | Read files, nodes, images, components, styles | | file_comments:write | Create, edit, and delete comments | | webhooks:write | Create and manage webhooks | | file_variables:read | Read variables and variable collections | | file_variables:write | Create and update variables |

After the user authorizes your app, Figma redirects to your redirect_uri with a code query parameter. Exchange the code for an access token.

curl -X POST "https://api.figma.com/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "grant_type=authorization_code"

The response includes:

| Field | Type | Description | |-------|------|-------------| | access_token | string | The token to use in API requests | | refresh_token | string | Used to obtain a new access token when the current one expires | | expires_in | number | Token lifetime in seconds (typically 14400 = 4 hours) |

With OAuth, use the standard Authorization: Bearer header instead of X-Figma-Token.

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://api.figma.com/v1/me"

Access tokens expire after the duration specified in expires_in. Use the refresh token to obtain a new access token without requiring the user to re-authorize.

curl -X POST "https://api.figma.com/v1/oauth/refresh" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

The response contains a new access_token and refresh_token. Store the new refresh token -- each refresh token is single-use.