Skip to main content
With the Square integration, you can manage seller team access through Opal:
  • Let people request just-in-time access to Square locations from the web and Slack
  • Deactivate and reactivate team members who already exist in Square
  • Review who is assigned to each location and job
  • Delegate approvals to the right owners
Square does not have staff groups. Locations are the membership you can grant. Jobs sync for visibility only.

​
Supported resources

​
Requirements

Before you begin, you must:
  • Be an Opal Admin.
  • Be able to open the Square Developer Console for the seller account you want to connect.
  • Your Opal tenant must be on version 1.1248.0 or later. If you do not see Square under + App, contact your Opal admin or Opal support.
Opal connects customer accounts to production Square. Use the production access token for that seller, not a Sandbox token.

​
1. Copy the production access token

Opal authenticates with the application’s production access token. That token is a personal access token for your own Square account.
  1. Sign in to the Square Developer Console.
  2. Open an application, or create one (for example, Opal).
  3. In the left pane, choose Credentials.
  4. At the top of the page, choose Production.
  5. In Production Access token, choose Show and copy the token.
Square shows how these credentials work in Access tokens and other credentials.
A production access token can call every Square API on that seller account, including payments. Opal only calls the Team and Locations APIs. Store the token in Opal and do not share it. This setup is for your own Square account. Do not collect personal access tokens from other sellers.

​
2. Create a Square app in Opal

In Opal, go to Inventory > + App, then select Square. Fill in the following fields and create the app. Opal reads the merchant id from the token. You do not enter it.

​
3. Check the app setup

After you create the app, open Setup. Opal checks the token against Square. A production access token also includes other Square permissions, such as payments and customers. Opal lists those on Setup as Token includes scopes outside team and merchant profile. That result is expected for this token. Opal does not call those APIs. If Employees read or Merchant profile read is missing, the app is not healthy and sync does not run. If Employees write is missing, Opal can still import, and grants, revokes, and status changes do not run.

​
4. Import Square items

Active team members who have an email address appear on the app’s Accounts tab after sync. Import locations and jobs from … > Import items. Filter by Square Location or Square Job. People can then request Square locations through Opal. Opal skips inactive team members and team members with no email address, or with an email that is not a valid address. They are not listed as accounts until they are active and have an email.

​
Team members

Create the person in the Square Dashboard before you grant them access in Opal. Square does not let Opal send the team invitation, and there is no API status for invited versus joined. A permission set and passcode, which the person needs in order to sign in, are also set in the Square Dashboard. When user provisioning is enabled:
  • Already active in Square: Opal links that team member. It does not create a second one.
  • Inactive in Square: Assigning access reactivates that same team member.
  • Not in Square: Opal refuses the grant and tells you to create them in the Square Dashboard, including a permission set and passcode, then sync again.
  • Remove from the connection: Opal sets the team member to Inactive. Square has no delete for team members. Their location assignment can remain on the inactive member. The next sync drops them from Opal groups. History remains.
Opal matches people by email. If more than one Square team member has the same email, Opal stops instead of guessing which one to update.
Opal cannot change the Square account owner. Location grants, revokes, and deactivation for that person fail with Square cannot change the account owner.

​
Locations

A location grant adds that location to a team member who is assigned to a specific list of locations. A revoke removes that location. If it was their only location, the list is empty and they stay assigned to an explicit list.
Some team members are assigned to all current and future locations. The first time Opal grants or revokes one location for that person, Square stores an explicit list of the locations they have at that moment. A revoke leaves out the location you removed. Locations you create in Square later are not added automatically. Assign those in Opal or in Square.
Inactive locations are not imported.

​
Jobs

Jobs sync as groups so you can see who holds each job title. Opal does not add or remove job assignments because changing a job in Square also changes wage settings, and Opal does not write pay. If you rename a job in the Square Dashboard, the next sync updates the title in Opal.

​
What Opal does not manage

  • Creating a Square team member, or sending the Square team invitation
  • Permission sets and passcodes
  • Job assignment and pay
  • Customers, catalog, orders, payments, and the rest of the commerce APIs, even when the token includes those permissions
Last modified on November 4, 2026