Scopes for Enterprise User Access Token in REST API

REST API
1

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",
      },
    },
2

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.

3

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 :frowning:

4

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.

5

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'
}
6

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!

1 Like
7

Hi! I submitted the support ticket with the following information

2 Likes
8

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 ?

9

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

10

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

11

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.