Figma Plugin ↔ GitHub REST API: Unresolved OAuth Scope Negotiation Across Figma Updates

Scope Negotiation Strategy

To maintain stability across Figma updates and preserve backward compatibility, plugins should adopt an Incremental Authorization strategy paired with Header-based Scope Verification. Rather than requesting a comprehensive set of permissions upfront, the plugin should request the minimum viable scopes for core functionality and prompt for additional permissions only when a user triggers a feature that requires them.

Implementation Pattern

Since Figma does not provide a native runtime hook to detect external OAuth scope changes, the plugin must manually verify the token's capabilities during the initialization phase or before high-privilege API calls.

1. Verify Current Scopes: Call the GitHub GET /user endpoint. GitHub returns the currently authorized scopes in the X-OAuth-Scopes response header.
2. Compare Against Requirements: Compare the headers against a versioned list of required scopes stored in your plugin's configuration.
3. Graceful Degradation: If a required scope is missing, do not force a global re-authentication. Instead, disable the specific feature in the UI and provide a "Grant Permission" button that initiates a new OAuth flow with the additional scopes.

Handling Backward Compatibility

To ensure older plugin releases remain functional after a Figma update or a change in your backend scope requirements:

• Avoid Hard-Failures: Never wrap the entire plugin initialization in a scope check that throws an unhandled exception.
• Scoped Storage: Store the token in figma.clientStorage, but accompany it with a metadata key (e.g., auth_version) that tracks which version of your scope requirements the token was issued under.
• Fallback Logic: If an older plugin version encounters a token with newer, broader scopes, it should continue to function using the subset of permissions it understands.

Verification Command

You can verify the current scopes of a stored token using a simple curl request to check the headers:

curl -H "Authorization: token YOUR_ACCESS_TOKEN" https://api.github.com/user

Inspect the X-OAuth-Scopes header in the response to confirm which permissions are active.

Assumptions and Uncertainty

This approach assumes the use of standard GitHub OAuth apps. If you migrate to GitHub Fine-Grained Personal Access Tokens, the scope negotiation logic changes significantly as permissions are resource-specific rather than global. We assume the plugin uses a backend proxy or a secure handshake to exchange codes for tokens, as Figma plugins cannot securely store client secrets.

Diagnostic Detail Needed: Are you utilizing a middleware server to handle the OAuth exchange, or are you relying on a third-party authentication provider?