Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
OAUTH API

Get Right-Sized Permissions with Down-Scoped OAuth Tokens

The Square OAuth flow is for application developers who build applications that receive authorizations from the Square sellers who use their applications. This topic shows you how to get a set of access tokens for a single authorization where each token carries a different subset of the scope of the initial seller authorization.

Overview Permalink Get a link to this section

The seller's server application is responsible for getting the initial seller authorization and the fully scoped access token. After that, the server application is responsible for getting and caching scoped-down access tokens for use in the seller's client applications.

Note

The OAuth API call flow requires an initial seller authorization before an access token and a refresh token are granted. When you have a refresh token, you can get scoped-down access tokens.

A personal access token from the Square Developer Dashboard is not obtained in an OAuth flow, has no expiration, and cannot be scoped down.

Create a limited-scope OAuth access token Permalink Get a link to this section

Scoped-down access tokens are useful when the seller has a client web or mobile application that accesses a subset of Square account resources. For example, a seller might have a mobile application that is used only for maintaining inventory. In that case, the mobile client uses an access token that only provides permission for inventory operations. The mobile client, therefore, should not be given an access token that can create or update payments.

When a seller grants an application OAuth access to their account with a personal access token, the authorization can result in a set of permissions that is too broad for a scoped set of actions. For example, a seller can use the personal access token with MERCHANT_PROFILE_READ, PAYMENTS_READ, PAYMENTS_WRITE, BANK_ACCOUNTS_READ, and other permissions. The client might just need MERCHANT_PROFILE_READ to retrieve the business_name of the seller. A token containing all of a seller's authorizations presents an inherent security risk, because some permissions are sensitive and used in limited contexts (for example, PAYMENTS_WRITE). An intercepted token containing a full set of seller permissions can be used maliciously, which poses an increased security risk.

The scopes field is an optional field within the ObtainToken endpoint. The scopes field lets you define the set of permissions contained within the returned OAuth access token.

In the following example, assume that:

  • The seller grants an application access to the following scopes: <MERCHANT_PROFILE_READ>, PAYMENTS_READ, PAYMENTS_WRITE, ORDERS_READ, ORDERS_WRITE, BANK_ACCOUNTS_READ``INVENTORY_READ, INVENTORY_WRITE, and ITEMS_READ.

  • The seller wants to create a new OAuth access token strictly limited to the scopes that let the client read the catalog and update inventory: MERCHANT_PROFILE_READ, INVENTORY_READ, INVENTORY_WRITE, and ITEMS_READ.

Example Request

Obtain Token
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2021-01-21' \
  -H 'Content-Type: application/json' \
  -d '{
    "scopes": [
      "MERCHANT_PROFILE_READ",
      "INVENTORY_READ",
      "INVENTORY_WRITE",
      "ITEMS_READ"
    ],
    "grant_type": "refresh_token",
    "refresh_token": "<REFRESH_TOKEN>",
    "client_secret": "{APPLICATION_SECRET}",
    "client_id": "{APPLICATION_ID}"
  }'

Example Response

The seller's server application gets the scoped-down access token back from the ObtainToken endpoint and then provides it to the inventory mobile client. The client can now call the Square Catalog API and Inventory API.

200 Response
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2021-01-02T00:14:15Z",
  "merchant_id": "MERCHANT_ID",
  "refresh_token": "REFRESH_TOKEN",
  "short_lived": false
}

Note

  • The API response does not include a list of scopes. If a 200 Response is returned, it can be assumed that the scopes have been added to the newly created OAuth access token.

  • The newly created OAuth access token cannot be viewed in the Developer Dashboard. Your server application needs to store this new token for future reference.

  • The refresh token returned in the response can be used to get an access token.

Create a short-lived OAuth access token Permalink Get a link to this section

The default expiration for access tokens is 30 days. A 30-day lifespan is not appropriate for use in less secure web or mobile clients. The 30-day expiration increases the risk duration for exposure and abuse. When working within these client environments, developers prefer a credential with a shorter lifespan to prevent errors and mitigate risk.

The short_lived optional field within the ObtainToken endpoint lets developers generate a short-lived access token that expire 24 hours after creation. This provides optional flexibility for developers working in loosely controlled access environments.

Example

Assume that a developer wants to create a new OAuth access token that expires 24 hours after creation.

POST /oauth2/token

Obtain Token
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2021-01-21' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "{REFRESH_TOKEN}",
    "client_secret": "{APPLICATION_SECRET}",
    "client_id": "{APPLICATION_ID}",
    "short_lived": true
  }'

Example Sandbox Response

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2020-12-04T00:16:17Z",
  "merchant_id": "MERCHANT_ID",
  "refresh_token": "REFRESH_TOKEN",
  "short_lived": true
}

Note

The lifespan of the short-lived access token cannot be customized. It always has a 24-hour lifespan.

Revoke authorization for a single OAuth access token Permalink Get a link to this section

The default behavior for the Square RevokeToken endpoint terminates the entire authorization for a seller. However, there are reasons to create and expire specific access tokens without terminating the entire seller authorization. For example, if an access token is compromised, developers want to revoke the compromised token and generate a new one without requiring a new seller authorization.

The revoke_only_access_token is an optional field in the RevokeToken endpoint. This field lets developers terminate a specified OAuth access token, without terminating the entire authorization.

Example

Assume that a developer realized that their OAuth access token has been compromised. The developer wants to revoke this token without losing seller authorizations.

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-01-21' \
  -H 'Authorization: Client APPLICATION_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "{ACCESS_TOKEN}",
    "client_id": "{CLIENT_ID}",
    "revoke_only_access_token": true
  }'

Example Response

{
  "success": true
}