OAuth API

How It Works

Use OAuth to securely manage permissions and access to Square merchant accounts.

Requirements and limitations

  • The OAuth API supports up to 500 authorizations per application. Contact support to enable applications for larger audiences.

  • The OAuth API requires HTTPS.

  • Square OAuth access tokens expire after 30 days with a grace period of 15 days. After expiration, applications must generate a new OAuth access token using the refresh token received when the authorization was first granted.

  • Refresh tokens do not expire. However, if you lose a refresh token, you must repeat the full OAuth flow to obtain a new OAuth access token and a refresh token.

What is OAuth?

All calls to Square API endpoints require access tokens. When you sign up for a Square account and create an application you get a personal access token. This personal access token gives full access to your account and to manage resources within your own account.

Now suppose an application integrates with Square to take payments and manage inventory. A Square account holder may sign up to use the application, but they need to give the application permission to perform tasks on their behalf. OAuth is the mechanism applications use to request permission from account holders to access their account. For information about OAuth specification, see OAuth 2.0.

The OAuth 2.0 specification defines the following 4 roles. In Square context these roles are:

  • Client — An application, not owned by Square using Square APIs or SDKs to integrate with Square services. Integrated clients are also sometimes called "3rd-party applications". 3rd-party applications can be single-user, custom solutions or official partner applications (like those listed in the Square App Marketplace).

  • Resource owner — The Square account holder that signup to use a 3rd-party application and grants the application permissions to access resources (such as catalog, customers, orders, and inventory) in their Square account.

  • Resource and Authorization servers — Square servers that issue OAuth access tokens and host resources in Square accounts. Neither developers nor Square account holders need to know the details.

Square OAuth process overview

Applications use the following process to obtain permission from Square accounts and get OAuth tokens to perform tasks on their behalf.

  1. Applications configure and serve a link with the scope parameter set to the desired OAuth permissions. For example: https://squareup.com/oauth2/authorize?client_id=exampleG9OlZgH7p4UszK_YIw-HeQ&scope=PAYMENTS_READ PAYMENTS_WRITE. Typically applications serve OAuth links as part of the sign-up workflow.
  2. After the Square account holder clicks the authorization link, they are prompted with a permissions form hosted by Square:
    Oauth permissions screen
  3. When the account holder clicks Allow on the permission form, Square sends an OAuth authorization code to the redirect URL configured for the application.
  4. The client application uses the (short-lived) OAuth authorization code to request an OAuth access token from the ObtainToken endpoint.
  5. The ObtainToken endpoint responds with an OAuth access token and a refresh token.

Applications can use the OAuth access tokens to make subsequent calls with Square APIs and SDKs on behalf of the Square account holder and access resources in the associated Square account.

The following diagrams illustrate the process flow:

Oauth process flow

OAuth access token management

Square OAuth API supports distinct methods for acquiring an OAuth access token. In the ObtainToken request applications specify the grant_type parameter to identify the method and provide relevant information in the request body.

The methods of acquiring OAuth access token are:

  • An application received an authorization code and wants to exchange it for an OAuth access token. In this case, the application sets the following parameters in the request:

    • Set grant_type to authorization_code
    • Set code to the authorization code
  • An application has previously obtained an OAuth access token but it has expired. In this case, the application provides the following parameters:

    • Set grant_type to refresh_token
    • Set refresh_token to the refresh token it received earlier in the initial ObtainToken request
  • An application has a legacy OAuth access token that was obtained using API version 20190313 or earlier. In this case, the application provides the following parameters:

    • Set grant_type to migration_token
    • Set migration_token to the legacy OAuth access token

    In response ObtainToken returns a new OAuth access token and a new refresh token.

Best practices

  • Store OAuth tokens securely. Application clients should never interact with OAuth tokens and OAuth tokens should never be stored in plaintext.
  • Adhere to the principle of least privilege. Applications should never request more than the minimum permissions needed to function properly.
  • Use OAuth for authorization whenever possible. OAuth tokens let users control access to their own accounts and strengthens application security.
Next
OAuth Setup Guide >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow