OAuth

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.

Overview Permalink Get a link to this section

OAuth tokens used with Connect v1 endpoints are scoped to individual seller locations. To get an OAuth token, a seller is challenged for credentials, selects one of the seller locations, and is authorized the permissions requested by your application.

OAuth tokens used with Square API endpoints are scoped to the seller level and do not specify a seller location ID to be applied to API operations. In some cases, a Square API endpoint requires a location ID in the body of a request; otherwise, it can be optional. After your application gets a seller-scoped OAuth token, the previous location-scoped OAuth token should be revoked.

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.

To learn about how to get a Square API OAuth token, see OAuth API: Walkthrough.

Create a new application registration Permalink Get a link to this section

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 of 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 will contain a location_id.

Update your OAuth application logic Permalink Get a link to this section

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

Let the seller select a seller location Permalink Get a link to this section

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.

Make a Square API call Permalink Get a link to this section

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:

curl https://connect.squareup.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2020-07-22' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "idempotency_key": "894f8311-dbd8-4ae6-a7db-1c15eecce98a",
    "source_id": "SOURCE_ID",
    "accept_partial_authorization": false,
    "autocomplete": true,
    "location_id": "90A9W5RRYD2GQ"
  }'

Revoke location-scoped access tokens Permalink Get a link to this section

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 Revoke OAuth Tokens.

Revoke an access token request Permalink Get a link to this section

In the following request, {{CLIENT_SECRET}} is issued to the original Connect v1 application that you are replacing with a new application. {{APPLICATION_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.

curl https://connect.squareup.com/oauth2/revoke \
  -X POST \
  -H 'Square-Version: 2020-07-22' \
  -H 'Authorization: Client {{CLIENT_SECRET}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_id": "{{MERCHANT_ID}}",
    "client_id": "{{APPLICATION_ID}}",
    "revoke_only_access_token": false
  }'

Revoke a token response Permalink Get a link to this section

A success response looks like the following:

{
  "success": true
}

A failure occurs if the {{APPLICATION_ID}} and the {{CLIENT_SECRET}} are not for the same application:

{
  "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.