OAuth API Reference

OAuth

OAuth Overview

Before other Square merchants can use your application, they need to grant it permission to make API calls on their behalf. Your application can use OAuth for this purpose.

Note: You don't need to use OAuth if you're if you're just building an application for your own use. Your personal access token gives you full API access to your account.

What is OAuth?

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

  • A Square merchant
  • Your application's client (the website or mobile app that the merchant uses)
  • Your application's back-end server
  • Square's OAuth HTTPS endpoints

At the end of these exchanges, your application receives an access token that it uses to make API calls on the merchant's behalf. Your application uses this access token just like it uses your personal access token.

Why use OAuth?

It might seem complicated at first, but OAuth makes things simpler for both you and the merchants using your application, and it reduces security risks for everyone:

  • Your application doesn't need to store merchant passwords (and it definitely shouldn't).
  • Merchants don't need to sign in to Square every time they use your application.
  • You can pick which permissions to request from a merchant. For example, merchants can grant your application access to their items library, without also needing to grant access to their transaction history.
  • Merchants can revoke a potentially insecure application's access without affecting other applications or needing to reset their password.

Implementing OAuth

Initial setup: Specify a redirect URL

During the OAuth flow, Square directs the merchant's web browser to a URL that you specify (called the redirect URL). Your application's back-end server is responsible for handling requests sent to this URL.

While you're developing your application, its redirect URL can point to localhost. For example, the oauth-flow.py sample asks you to set your redirect URL to http://localhost:8080/callback.

However, when you finally deploy your app to other merchants, your redirect URL should not point to localhost. Instead, it should point to a publicly accessible location.

To set your redirect URL, open your application's control panel from the application dashboard. On the OAuth tab, specify your redirect URL in the appropriate field and click Save.

Flow step 1: Request permission from the merchant

To begin the OAuth flow, your application client (i.e., a webpage or mobile app) directs a Square merchant's web browser to a URL with the following format:

https://connect.squareup.com/oauth2/authorize?<PARAMETERS>

(The oauth-flow.py sample does this by hosting a simple link at http://localhost:8080.)

In order for the URL above to be valid, you must append a combination of the following query parameters to it:

NameTypeDescription
client_idstring

Required. Your application's ID, available from the application dashboard.

scopestring

Optional. A space-separated list of the permissions your application is requesting. These permissions determine which API endpoints your application is allowed to communicate with.

Supported values are described in Permission scope.

Note that because this string includes spaces, it must be URL-escaped.

Default value: MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ

localestring

Optional. The locale to present the permissions form in. Provide this value only if you are certain of the merchant's preferred locale. If you don't provide this value, Square detects the locale automatically.

Currently supported values are en-US, en-CA, es-US, fr-CA, and ja-JP.

sessionboolean

Optional. If false, the Square merchant must sign in to Square to view the permissions form, even if they already have a valid user session.

Default value: true

statestring

Optional. If you provide this value, it's passed along to your redirect URL after the merchant submits the permissions form. Include this parameter and verify its value to help protect against cross-site request forgery.

For example, a valid authorization URL resembles the following:

https://connect.squareup.com/oauth2/authorize?client_id=abc123&scope=PAYMENTS_WRITE%20PAYMENTS_READ&state=somestring

When a merchant visits this URL and signs in to Square, the permissions form is displayed:

The permissions form explains which permissions your application is requesting. If the merchant is comfortable with the permissions listed, they click Allow. Otherwise, they click Deny.

Flow step 2: Check the permissions form result

When the merchant submits the permissions form, their browser is automatically redirected to your redirect URL. The URL includes query parameters that indicate the result of the form submission.

If the merchant clicked Deny (or if the authorization failed for some other reason), the URL includes the following query parameters:

NameTypeDescription
errorstring

The type of error that occurred. If the merchant clicked Deny, this value is access_denied.

error_descriptionstring

A description of the error that occurred. If the merchant clicked Deny, this value is user_denied.

If the merchant clicked Allow, the URL instead includes a code query parameter. The value of this parameter is an authorization code.

(The oauth-flow.py sample simply checks whether a code query parameter is present in the URL, and assumes an error occurred if not.)

Flow step 3: Exchange your authorization code for an access token

After your redirect URL receives an authorization code, your back-end server can exchange it for an access token. To do so, your server sends a POST HTTPS request to the following URL:

https://connect.squareup.com/oauth2/token

The body of your request is a JSON object with the following format:

{
  "client_id": "YOUR_APPLICATION_ID",
  "client_secret": "YOUR_APPLICATION_SECRET",
  "code": "YOUR_AUTHORIZATION_CODE"
}

(Substitute your authorization code for YOUR_AUTHORIZATION_CODE.)

The values you substitute for YOUR_APPLICATION_ID and YOUR_APPLICATION_SECRET are available from your application dashboard.

The body of Square's response to your HTTPS request is a JSON object with the following format:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2016-08-10T19:42:08Z",
  "merchant_id": "YOUR_BUSINESS_ID"
}

The value of the access_token field is your newly created access token! You can now use it to make API calls on behalf of the authorizing merchant (see Request and response headers to learn how). The token tells Square which merchant you're acting on behalf of, and which permissions your application has been granted.

Flow step 4: Renew your access token periodically

Access tokens besides your personal access token expire every thirty days. If you make a request to a Connect API endpoint with an expired access token, the endpoint responds with a 401 Unauthorized error.

Your server can renew an expired access token by sending a POST request to the following URL:

https://connect.squareup.com/oauth2/clients/YOUR_APPLICATION_ID/access-token/renew

(Replace YOUR_APPLICATION_ID with your application's ID.)

The body of your request is a JSON object with the following format:

{
  "access_token": "YOUR_EXPIRED_ACCESS_TOKEN"
}

The body of Square's response is the same format as the one described in Flow step 3. Your newly renewed access token is available in the access_token field.

You cannot renew an access token that has been expired for more than fifteen days. Instead, the associated merchant must complete the OAuth flow from the beginning.

Flow summary

  1. Your application client requests permission from the merchant (by opening the permissions form in a web browser).
  2. The merchant grants permission.
  3. Square sends an authorization code to your server.
  4. Your server exchanges the authorization code for an access token (with the Obtain Token endpoint).
  5. Your application uses the access token in requests to the Connect API.
  6. Your server renews the access token every 30 days (with the Renew Token endpoint).

Permission scope

When you direct a merchant to the permissions form, you specify the scope of the permissions your application will have. You should request only the permissions your application requires.

Note that you automatically have all permissions when you use your application's personal access token with your own Square account.

Permissions correspond to Connect API endpoints as follows:

PermissionEndpoints
MERCHANT_PROFILE_READGET endpoints related to a merchant's business and location entities. Almost all Connect API applications need this permission in order to obtain a merchant's location IDs.
PAYMENTS_READGET endpoints related to transactions and refunds.
PAYMENTS_WRITEPOST, PUT, and DELETE endpoints related to transactions and refunds. E-commerce applications must request this permission.
CUSTOMERS_READGET endpoints related to customer management.
CUSTOMERS_WRITEPOST, PUT, and DELETE endpoints related to customer management.
SETTLEMENTS_READGET endpoints related to settlements (deposits).
BANK_ACCOUNTS_READGET endpoints related to a merchant's bank accounts.
ITEMS_READGET endpoints related to a merchant's item library.
ITEMS_WRITEPOST, PUT, and DELETE endpoints related to a merchant's item library.
ORDERS_READGET endpoints related to a merchant's Square online store.
ORDERS_WRITEPOST, PUT, and DELETE endpoints related to a merchant's Square online store.
EMPLOYEES_READGET endpoints related to employee management.
EMPLOYEES_WRITEPOST, PUT, and DELETE endpoints related to employee management.
TIMECARDS_READGET endpoints related to employee timecards.
TIMECARDS_WRITEPOST, PUT, and DELETE endpoints related to employee timecards.

The reference for each Connect API endpoint indicates which permissions are required to use that endpoint on a merchant's behalf.

Understanding credentials

The OAuth flow involves a few different credentials that you should treat with different levels of security.

Application ID

This is Square's unique identifier for your application. You provide it as a URL parameter when directing merchants to the permissions form. This lets Square know which application the merchant is authorizing.

Your application ID is not a secure credential, because you provide it as plaintext in a URL. You do not need to take extra precautions when using your application ID.

You can find your application ID on the application dashboard.

Application secret

This is a key that Square assumes only your application knows about. You provide it in an Authorization header when sending requests to the Obtain Token and Renew Token endpoints.

Store your application secret only on your server. Application clients should never interact with your application secret.

You can find your application secret on the application dashboard. If you have reason to believe it's been compromised, you can also replace it there.

Authorization code

This is the one-time-use code that Square sends your server when a merchant clicks Allow on the permissions form. You provide it as a body parameter in your request to the Obtain Token endpoint.

The authorization code is not secure by itself, because it is provided as plaintext in a URL. However, because you provide it along with your application secret, Square knows your request is legitimate and responds with an access token.

Access token

See Access token details.

Webhook signature key

This is a key that Square uses to sign all webhook notifications it sends to your specified notification URL. See Webhooks Overview for more information.

Store your signature key only on your server. Application clients should never interact with your signature key.

You can find your signature key on the application dashboard. If you have reason to believe it's been compromised, you can also replace it there.

Access token details

An access token represents the authorization a particular merchant has granted your application. You provide it in an Authorization header when sending requests to Connect API endpoints on the merchant's behalf.

Store access tokens only on your server. Application clients should never interact with access tokens.

Format

OAuth access tokens are ASCII strings no greater than 64 bytes in length.

Expiration

OAuth access tokens besides your personal access token expire after thirty days. It is your responsibility to renew access tokens with the Renew Token endpoint after they expire.

You cannot renew an access token that has been expired for more than fifteen days. Instead, the associated merchant must complete the OAuth flow from the beginning.

If you attempt to renew an unexpired token, the token's lifetime is not extended.

If you send a request to a Connect API endpoint with an expired token, the endpoint responds with 401 Unauthorized and returns an error object with a type field with the value oauth.expired. See Handling errors for more information on Connect API errors.

Revocation

You can revoke a merchant's access token with the Revoke Token endpoint. Note that if a merchant has more than one access token for your application, this endpoint revokes all of them, regardless of which one you specify.

The personal access token

This token represents your application's authorization for your own Square account. Use this token if you're developing an application only for yourself, or if you want to try out the Connect API without implementing OAuth. Personal access tokens never expire, and they automatically have all available permissions.

You can find your personal access token on the application dashboard. If you have reason to believe it's been compromised, you can also replace it there.

Fixing common errors

If an OAuth endpoint returns an error message instead of the values you expect, check here for the cause and the most likely solution.

"Invalid client or client secret"

An incorrect application secret was provided in a request to the Obtain Token endpoint. Make sure you copied the entirety of your application's secret from your developer dashboard, and that you aren't accidentally using a different application's secret.

"Invalid code"

An incorrect authorization code was provided in a request to the Obtain Token endpoint. The two most common causes of this are:

  • The authorization code does not match the value provided to your Redirect URL.
  • It's been long enough since the authorization code was issued that it has expired. In this case, return to the Authorize endpoint to generate a new authorization code and try again.

"Unauthorized"

In most cases, an incorrect access token was provided in the header of a request to a Connect API endpoint. Make sure you that you provided the right token, and that you provided it in an HTTP header with the following format:

Authorization: Bearer ACCESS_TOKEN

Authorize

GET /oauth2/authorize

You direct a merchant's web browser to this URL to present the permissions form that begins the OAuth flow. The form describes which permissions your application is requesting. It looks like this:

See Flow step 1: Request permission from the merchant for more information.

Request Parameters

For GET and DELETE endpoints, you provide request parameters in a query string appended to the request URL.

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

response_type (optional)string

Indicates whether you want to receive an authorization code (code) or an access token (token) from Square's response to your application's Redirect URL.

If you specify code, you must then exchange the authorization code for an access token with the Obtain Token endpoint.

Default value: code

scope (optional)string

A space-separated list of the permissions your application is requesting. Valid permissions are listed in Permission scope.

Default value: MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ

locale (optional)string

The locale to present the Permission Request form in. Provide this value only if you have ascertained the merchant's preferred locale. If you don't provide this value, Square detects the locale automatically.

Currently supported values are en-US, en-CA, es-US, fr-CA, and ja-JP.

sessionboolean

If false, the Square merchant must log in to view the Permission Request form, even if they already have a valid user session.

Default value: true

state (optional)string

If you provide this value, it's passed along to your application's Redirect URL after the Permission Request form is submitted. Include this parameter and verify its value to help protect against cross-site request forgery.

plan_id (optional)string

The ID of the subscription plan to direct the merchant to sign up for, if any. See Subscriptions Overview for more information.

You can provide this parameter with no value (plan_id=) to give a merchant the option to cancel an active subscription.

Return Value

When a merchant submits the Permissions form, the Square OAuth server calls back to your request's redirect_uri. The parameters included in the request's URL depend on whether authorization succeeded.

If authorization succeeded, the parameters are as follows:

NameTypeDescription
response_typestring

The same value you provided for response_type (either code or token).

codestring

An authorization code you can exchange for an access token with the Obtain Token endpoint.

This parameter is present only if you specify code as the value for response_type.

access_tokenstring

Your application's access token. You provide this token in a header with every request to Connect API endpoints. See Request and response headers for the format of this header.

This parameter is present only if you specify token as the value for response_type.

merchant_idstring

The ID of the merchant business that authorized the application.

This parameter is present only if you specify token as the value for response_type.

subscription_idstring

The ID of the merchant subscription associated with the authorization, if any.

This parameter is present only if response_type is token. If response_type is code, subscription information is instead returned by the Obtain Token endpoint.

plan_idstring

The ID of the subscription plan the merchant signed up for, if any.

This parameter is present only if response_type is token. If response_type is code, subscription information is instead returned by the Obtain Token endpoint.

statestring

The same value you specified for state in your original request, if any.

If authorization failed, either because the merchant denied access or because an error occurred, the parameters of the request are as follows:

NameTypeDescription
errorstring

The type of error that occurred. If the merchant denied your application access, this value is access_denied.

error_descriptionstring

The reason the error occurred. If the merchant denied your application access, this value is user_denied.

Example Request

https://connect.squareup.com/oauth2/authorize?client_id=YOUR_APPLICATION_ID&state=somestring

Obtain Token

POST /oauth2/token

After a merchant authorizes your application with the permissions form, an authorization code is sent to the application's redirect URL (See Implementing OAuth for information about how to set up the redirect URL). You exchange the authorization code for an access token with a request to this endpoint.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

client_secretstring

Your application's secret, available from the application dashboard.

codestring

The authorization code to exchange.

Return Value

A JSON object with the following fields:

NameTypeDescription
access_tokenstring

Your application's access token. You provide this token in a header with every request to Connect API endpoints. See Request and response headers for the format of this header.

token_typestring

This value is always bearer.

expires_atstring

The date when access_token expires, in ISO 8601 format.

merchant_idstring

The ID of the authorizing merchant's business.

subscription_idstring

The ID of the merchant subscription associated with the authorization, if any.

plan_idstring

The ID of the subscription plan the merchant signed up for, if any.

Example Request Body

{
  "client_id": "YOUR_APPLICATION_ID",
  "client_secret": "YOUR_APPLICATION_SECRET",
  "code": "M-Q7k-N0Emx_3cBqwbVLTQ"
}

Example Response Body

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2014-01-10T19:42:08Z",
  "merchant_id": "MERCHANT_BUSINESS_ID"
}

Renew Token

POST /oauth2/clients/{client_id}/access-token/renew

OAuth access tokens besides your application's personal access token expire after 30 days. Use this endpoint to renew a token before it expires. You can also renew expired tokens within 15 days of their expiration.

You cannot renew an access token that has been expired for more than 15 days. Instead, the associated merchant must complete the OAuth flow from the beginning.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with your application's secret, available from the application dashboard.

Path Parameters

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
access_tokenstring

The token you want to renew.

Return Value

A JSON object with the following format:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2014-01-10T19:42:08Z",
  "merchant_id": "YOUR_MERCHANT_ID"
}

The value of access_token is the renewed access token. This value might be different from the access_token you provided in your request. You provide this token in a header with every request to Connect API endpoints. See Request and response headers for the format of this header.

The value of expires_at indicates when your new access token expires, in ISO 8601 format.

Example Request Body

{
  "access_token": "YOUR_ACCESS_TOKEN"
}

Revoke Token

POST /oauth2/revoke

You can use this endpoint to revoke an access token generated with the OAuth flow.

If a merchant has more than one access token for your application, this endpoint revokes all of them, regardless of which token you specify.

If you revoke a merchant's access token, all of the merchant's active subscriptions associated with your application are canceled immediately.

Important: Unlike with other endpoints, the Authorization header you provide to this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with your application's secret, available from the application dashboard.

Request Parameters

For POST and PUT endpoints, you provide request parameters as JSON in your request's body.

NameTypeDescription
client_idstring

Your application's ID, available from the application dashboard.

access_tokenstring

The access token of the merchant whose token you want to revoke.

Do not provide a value for merchant_id if you provide this parameter.

merchant_idstring

The ID of the merchant whose token you want to revoke.

Do not provide a value for access_token if you provide this parameter.

Return Value

If the request is successful, the endpoint returns the following object:

{"success" : true}