Skip to main content
Question

Scopes for Enterprise User Access Token in REST API


This is a question related to obtaining access tokens for users within an Enterprise organization on the Figma.

Based on the documentation, it seems that the “file_variables:read” scope is required to read variables in Figma files, and this is specifically mentioned to be available for members in Enterprise organizations. https://www.figma.com/developers/api#authentication-scopes

We’ve noticed that the “file_read” scope is deprecated for OAuth 2 tokens when attempting to obtain an access token for an Enterprise user. It didn’t return any error nor access token.

Our team has been testing the API on personal accounts, and when we call Auth API for personal Figma accounts, it passed back the result(access token, expires in, refresh token) to my application.

Should we exclusively use the “file_variables:read” scope, or are there any additional considerations or scopes that need to be taken into enterprise accounts?

For your reference, this what my oauth calling API look like

id: "figma",
    name: "Figma",
    type: "oauth",
    authorization: {
      url: "https://www.figma.com/oauth",
      params: {
        scope: "file_read", // Should I add this scope as well for enterprise users? file_variables:read, file_variables:write
        response_type: "code",
      },
    },
This topic has been closed for comments

10 replies

James_Yang
Figmate
  • Figmate
  • 82 replies
  • November 30, 2023

The file_read scope is deprecated, so file_variables:read and file_variables:write are the correct scopes to use here.

We deprecated the file_read scope because it give access to too many endpoints. There are more granular scopes now to allow you to create tokens with more fine-grained access.


  • Author
  • 9 replies
  • November 30, 2023

Even if nothing comes back—no access token, no error—is there a chance there’s some enterprise/organization level account that doesn’t allow the members’ access in the enterprise plan sharable?

Probably my code has an issue tho 😦


James_Yang
Figmate
  • Figmate
  • 82 replies
  • December 1, 2023

If you’re getting nothing back at some step in the OAuth authentication flow, then this probably isn’t a scope issue. You might be making in a incorrect call somewhere or missing some error handling.


  • Author
  • 9 replies
  • December 1, 2023

Instead of using file_read, I tested with file_variables:read,file_variables:write,file_comments:write

I got 403 error

[next-auth][error][OAUTH_CALLBACK_ERROR] 
https://next-auth.js.org/errors#oauth_callback_error expected 200 OK, got: 403 Forbidden {
  error: OPError: expected 200 OK, got: 403 Forbidden
      at processResponse (webpack-internal:///(rsc)/./node_modules/openid-client/lib/helpers/process_response.js:37:15)
      at Client.userinfo (webpack-internal:///(rsc)/./node_modules/openid-client/lib/client.js:1126:22)
      at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
      at async oAuthCallback (webpack-internal:///(rsc)/./node_modules/next-auth/core/lib/oauth/callback.js:136:23)
      at async Object.callback (webpack-internal:///(rsc)/./node_modules/next-auth/core/routes/callback.js:18:79)
      at async AuthHandler (webpack-internal:///(rsc)/./node_modules/next-auth/core/index.js:202:38)
      at async NextAuthRouteHandler (webpack-internal:///(rsc)/./node_modules/next-auth/next/index.js:50:30)
      at async NextAuth._args$ (webpack-internal:///(rsc)/./node_modules/next-auth/next/index.js:85:24)
      at async /Users/mijinkim/Desktop/thinkspace/commentify/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:62499 {
    name: 'OAuthCallbackError',
    code: undefined
  },
  providerId: 'figma',
  message: 'expected 200 OK, got: 403 Forbidden'
}

James_Yang
Figmate
  • Figmate
  • 82 replies
  • December 1, 2023

So this is only happening with file_variables:read,file_variables:write,file_comments:write and not file_read?

I still suspect there’s something else going on here. Since this is turning into an involved debugging session, it would be great if you could file a support ticket with the details above, plus the following:

  • Your full OAuth authentication code with a pointer to the line where it is failing
  • Which Figma endpoint you’re getting a 403 from
  • The actual response body of the 403 response

Thanks!


  • Author
  • 9 replies
  • December 3, 2023

Hi! I submitted the support ticket with the following information


  • Author
  • 9 replies
  • December 4, 2023

I’ve confirmed that using file_read for OAuth allows full access to the desired endpoints with an enterprise account token. However, with the scopes file_variables:read and file_variables:write , the token request isn’t working, and I’m not receiving a return. Could you please check the endpoint https://www.figma.com/api/oauth/token ?


Dima_Zhukov

Confirm same issue, variable scope is missing when I create new access token


James_Yang
Figmate
  • Figmate
  • 82 replies
  • December 11, 2023

Hi Dima, this is a different issue. The variables scopes are only available when you are in an organization on the Enterprise plan.


  • Author
  • 9 replies
  • December 11, 2023

I will share the support reply from the associated support ticket.


Hi Mijin,

Thank you for that. It appears from the message that the token still doesn’t have the files:read scope, which is necessary to call that endpoint. The token needs to have all the scopes needed to call all the endpoints to be used, so if you want to get projects in a team as well as get/modify variables in a file, then the token should have scopes files:read,file_variables:read,file_variables:write


If you wish to acquire a token and ensure its functionality for the intended endpoints, it is advisable to include the files:read scope in your token request. However, it’s worth noting that the Figma developer REST API documentation explicitly states, “Note: the file_read scope is deprecated for OAuth 2 tokens. Please migrate your application to use the scopes above.

This statement may cause confusion for most REST API developers who are issuing tokens to access files on behalf of users and creating extension tools.

Previously, in the context of developing Figma extension tools for enterprise users, it seems there is a need for improvement in the development documentation for enterprise accounts.


Cookie policy

We use cookies to enhance and personalize your experience. If you accept you agree to our full cookie policy. Learn more about our cookies.

 
Cookie settings