Permission Getting Removed - Insufficient Scope Issue

Questions
1

We are seeking clarification regarding a permission/scopes issue encountered with one of our merchants.

Merchant ID: LF5MJAE8HBJT4

We recently identified that the merchant’s webstore integration stopped functioning due to the following error:

SquareApiException while updating order [{"errors":[{"category":"AUTHENTICATION_ERROR","code":"INSUFFICIENT_SCOPES","detail":"The merchant has not given your application sufficient permissions to do that. The merchant must authorize your application for the following scopes: ORDERS_READ"}]}]

After asking the merchant to re-authorize the application permissions, the integration immediately started functioning correctly again.

What we are trying to understand is how a previously granted permission/scope (ORDERS_READ) became unavailable in the first place.

From our side:

  • Our platform only supports requesting/granting the required scopes during authorization.

  • We do not have any functionality or API flow implemented to remove or downgrade permissions/scopes for a merchant.

  • No intentional changes were made from our side related to Square permissions.

From the merchant side:

  • The merchant stated they did not manually revoke permissions or modify app access/settings in Square.

We would appreciate clarification on the following:

  1. Under what circumstances can an already granted scope become unavailable or removed?

  2. Can Square automatically invalidate, downgrade, or remove scopes due to token refreshes, account changes, app setting updates, reauthorization flows, security actions, or other platform-level events?

  3. Is there any audit/event history available that can show:

    • when the permission/scope changed,

    • what triggered the change,

    • and whether it was initiated by the merchant, the application, or internally by Square?

  4. Are there any logs or APIs available that developers can use to track authorization scope changes for connected merchant accounts?

We are trying to identify the root cause so we can properly explain the behavior to the merchant and proactively monitor for similar situations in the future.

Any guidance would be greatly appreciated.

3

Thanks for the detailed question! Since the merchant says they didn’t revoke manually (and assuming your application isn’t calling the Revoke endpoint), the most likely culprit is your token refresh flow.

Two quick questions to help narrow this down:

  1. Do you have a token refresh flow built out? (i.e., are you calling ObtainToken with grant_type: refresh_token to get new access tokens?)

  2. If so, are you passing a scopes field in that request? If scopes is included, the new token gets restricted to only those scopes, so if ORDERS_READ was omitted, that permission would be silently dropped. Omittingscopes entirely preserves all originally granted permissions.

Let us know and we can dig further from there!

Relevant Docs:
Refresh, Revoke, and Limit Scope of OAuth Tokens
OAuth Best Practices

4

Hi Ashley,

Thanks for the guidance. We reviewed both our Core API and Merchant Web code paths.

To answer your questions:

  1. Yes, we do have a token refresh flow. We call ObtainToken with grant_type=refresh_token to renew Square access tokens.

  2. No, we are not passing a scopes field in the refresh token request.

Our refresh request only includes:

  • client_id
  • client_secret
  • grant_type = refresh_token
  • refresh_token

We confirmed that no scopes parameter is included during refresh, so based on the documentation, the refresh flow should preserve all originally granted permissions.

We also checked the initial authorization flow in Merchant Web. The Square OAuth URL is generated with the configured scope list, and the live configuration currently includes ORDERS_READ in the requested scopes. We did not find any alternate Square authorization path with a reduced scope list.

Additionally:

  • We do not call the Revoke endpoint as part of any automatic flow.
  • We do not have any functionality in Core API or Merchant Web to remove, downgrade, or update Square OAuth permissions for a merchant.
  • The only relevant token maintenance flow is the refresh flow described above, and it does not pass scopes.

Given this, it does not look like our application is reducing the granted permissions during token refresh or reauthorization.

Could you please help us investigate from Square’s side whether there is any audit/event history for merchant LF5MJAE8HBJT4 showing why ORDERS_READ became unavailable? Specifically, we would like to know whether the scope change was triggered by the merchant, Square, an app configuration change, a security action, or any other platform-level event.

Thanks again for helping us narrow this down.