The Basics

OAuth Overview

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

What is OAuth?

At a high level, the OAuth 2.0 protocol is a series of credential exchanges between:

  • A user account
  • An application frontend (e.g., website or mobile app)
  • An application backend
  • An OAuth HTTPS endpoint

These exchanges happen without requiring the user to do anything other than click a link or button to grant access to their account. At the end of these exchanges, the application receives an OAuth access token that it uses to make API calls on the user's behalf. Unlike a password or unscoped access token, which lets applications impersonate the account owner, OAuth access tokens are scoped to specific permissions that limit the behavior of the application. Scoped access tokens provides number of security advantages:

  • Applications do not request or store user credentials for the targeted account.
  • Users do not need to sign in to their account every time they use the application.
  • Users can grant access for specific resources instead of allowing access to their entire account. For example, merchants may grant access to only their items library without exposing their transaction history.
  • Users can revoke access for a potentially insecure application without affecting other applications or having to reset their password.

OAuth with Square APIs

The Square OAuth API lets applications request and obtain permission from a Square account to make API calls on behalf of that account. Applications can request individual permissions so that users do not need to grant full access to their Square accounts.

Requirements and limitations

  • The OAuth API supports up to 500 authorization tokens 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. Applications must manually renew expired access tokens within the 15 day grace period.
  • OAuth tokens cannot be renewed once the grace period expires. They must be regenerated with the full OAuth flow.
  • OAuth tokens cannot be renewed until they are at least 24 hours old.

How to use it

All calls to Square API endpoints require access tokens. Applications using OAuth need to request the OAuth token before interacting with other Square APIs. OAuth tokens can be requested once and reused until they expire so the OAuth flow should be incorporated as early as possible in the application workflow.

Square OAuth process overview

  1. The application serves an authorization link with the desired permissions as scope parameters.
  2. A user clicks the authorization link and is redirected to the OAuth permission form hosted by Square.
  3. The user clicks Allow and Square sends an authorization code to the application backend.
  4. The application backend uses the authorization code to request an OAuth token from the ObtainToken endpoint.
  5. The ObtainToken endpoint returns an OAuth token the application can use to make API calls against the user's account.
Oauth process flow

OAuth data model

Square OAuth is built on three elements: an authorization link, an authorization code, and an OAuth token.

The authorization link begins the OAuth flow by directing users to the OAuth permission form. The authorization URL makes a GET request to the Authorize endpoint using the following format:{PARAMETERS}

The authorization URL has 2 key parameters:

  • client_id — Required. The Square-issued ID of the application requesting access permission.
  • scope — Optional. A space-separated list of permissions the application is requesting.

If the scope parameter is missing the OAuth token will be scoped to the following permissions by default: MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ. See the OAuth API Technical Reference for the full list of available permission scopes.

Clicking on the authorization URL sends users to the Square permissions form.

Oauth permission form

When the user submits the permission form, their browser is automatically sent to your redirect URL with query parameters that indicate the result.

  • If the user clicks Allow, the return result includes a code parameter. The value of code is an authorization code can be exchanged for an OAuth token.
  • If the user clicks Deny, the return result includes error and error_description parameters.

Authorization code

When users click Allow on the Square permission form, Square returns a short-lived authorization code to the requesting application that can be exchanged for a longer-lived OAuth token. Authorization tokens are limited to the permissions detailed in the permission form and expire after 5 minutes.

OAuth token

OAuth tokens are scoped access tokens for API calls and only grant access to a Square account based on the permissions detailed in the original authorization 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 authentication whenever possible. OAuth tokens let users control access to their own accounts and strengthens application security.
OAuth Setup Guide >

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