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

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 does not carry a location ID because it is 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 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 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.

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:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -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": "cnon:card-nonce-ok",
    "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, the client secret value is issued to the original Connect v1 application that you are 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
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/oauth2/revoke \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Client APPLICATION_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "{ACCESS_TOKEN}",
    "client_id": "{CLIENT_ID}",
    "revoke_only_access_token": true
  }'

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