Migrate to the Square API OAuth Flow

This topic describes the migration tasks that update your application to use seller-scoped OAuth tokens appropriate for calling Square API endpoints. For a complete discussion of Square's current OAuth process, see OAuth API Overview.

Link to section

Overview

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.

Important

You must migrate your application OAuth code to get a seller-scoped OAuth token before your application can make calls on the Square API.

After your application gets a seller-scoped OAuth token, the previous location-scoped OAuth token should be revoked.

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

Link to section

Create a new application registration

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 Dashboard 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.

Link to section

Update your OAuth application logic

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.
Link to section

Let the seller select a seller location

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.

Link to section

Make a Square API call

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:

Create payment

Link to section

Revoke location-scoped access tokens

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.

Link to section

Revoke an access token request

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.

Revoke token

Link to section

Revoke a token response

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

Note

Location-scoped access tokens for Connect v1 endpoints cannot be migrated to seller-scoped access tokens. They must be revoked or allowed to expire.