Migrate to the Square API OAuth Flow

Applies to: OAuth API | Locations API | Payments API

Learn how to use the OAuth API to update your application to use seller-scoped OAuth tokens appropriate for calling Square API endpoints.

An OAuth token used with Connect v1 endpoints is associated with an individual seller location. Each seller location is individually authorized to call Connect v1 endpoints. To get a Connect v1 token, the Square authorization web page challenges a seller for credentials, lets the seller select one of their locations, and authorizes your application for the requested permissions.

An OAuth token used with a Square API endpoint is associated to the seller and works with all of the seller's locations. The token doesn't carry a location ID because it's scoped at the seller level. Some Square API endpoints require a location ID in the body of a request. Otherwise, the ID is be optional. When an ID is required, your application gets the ID and provide it in the API call. Use the ListLocations endpoint to get the seller's locations to be populated in a list for the seller to select from.

To learn how to get a Square API OAuth token, see OAuth Walkthrough: Test Authorization with a Web Server.

To integrate with the Square API and make calls using a seller-scoped OAuth access token, you must replace the existing Connect v1 application ID for your application. To do this, create a new application registration in the Developer Console to get the new application ID. Be sure to add Square webhook subscriptions to replace any v1 webhook subscriptions that you might have configured in your original application.

The new application uses seller-scoped tokens with webhook subscriptions that include events from all the seller's locations. Previously, webhook events were limited in scope to only the location that was authorized. When a Square webhook notification applies to an operation scoped to a seller location, the body of the notification contains a location_id.

Assuming that your application instance has a deprecated location-scoped access token, complete the following steps to get a new seller-scoped access token:

1. Link to the Square authorization page.
2. Exchange the authorization code for OAuth tokens.
3. Add a Location selection modal window to the application sign-in screen.

In the original Connect v1 authentication flow for non-location-aware sellers, a seller is prompted to select a location to sign in to. Your Square API application must require a seller to select a location after signing in. Your application must retrieve a list of locations and show a selection list to a seller.

When your application has a new OAuth access token and location ID, use these values to make a Square API call like the following CreatePayment call that creates a payment to be applied to the location selected by the user in the previous step:

After you test your new application and put it into production, you need to revoke access to your Connect v1 application. To do this, revoke any access tokens that were issued for the old application ID. For more information, see Refresh, Revoke, and Limit the Scope of OAuth Tokens.

In the following request, the client secret value is issued to the original Connect v1 application that you're replacing with a new application. {CLIENT_ID} is the application ID of your original Connect v1 application. To get the merchant ID of the seller whose tokens are to be revoked, sign in to the seller Square account and navigate to https://squareup.com/tracking.json.

A success response looks like the following:

{
  "success": true
}

A failure occurs if the values for the client ID and client secret come from different applications.

{
  "message": "Not Authorized",
  "type": "service.not_authorized"
}