Authorization API Reference

OAuth API

OAuth Overview

Before other Square accounts 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 are just building an application for your own use but be aware that your personal access token provides unrestricted access to your Square account.

OAuth Permissions

When you direct your user to the permissions form, you specify the scope of the permissions your application will have. You should only request 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.

Permission Method Description and Example Usage
BANK_ACCOUNTS_READ GET

Grants read access to bank account information associated with the targeted Square account.

EXAMPLE: Required to call the Connect v1 Bank Accounts API.

CUSTOMERS_READ GET

Grants read access to customer information.

EXAMPLE: Required to call the ListCustomers endpoint.

CUSTOMERS_WRITE

POST

PUT

DELETE

Grants write access to customer information.

EXAMPLE: Required to create and update customer profiles.

EMPLOYEES_READ GET

Grants read access to employee profile information.

EXAMPLE: Required to call the the Connect v1 Employees API.

EMPLOYEES_WRITE

POST

PUT

DELETE

Grants write access to employee profile information.

EXAMPLE: Required to create and modify employee profiles.

ITEMS_READ GET

Grants read access to product catalog information.

EXAMPLE: Required to call the ListCatalog endpoint.

ITEMS_WRITE

POST

PUT

DELETE

Grants write access to product catalog information.

EXAMPLE: Required to modify or add to a product catalog.

MERCHANT_PROFILE_READ GET

Grants read access to business and location information.

EXAMPLE: Required to obtain a location ID for subsequent activity.

ORDERS_READ GET

Grants read access to order information.

EXAMPLE: Required to call the BatchRetrieveOrders endpoint.

ORDERS_WRITE

POST

PUT

DELETE

Grants write access to order information.

EXAMPLE: Required to call the CreateCheckout endpoint.

PAYMENTS_READ GET

Grants read access to transaction and refund information.

EXAMPLE: Required to call the RetrieveTransaction endpoint.

PAYMENTS_WRITE

POST

PUT

DELETE

Grants write access to transaction and refunds information.

EXAMPLE: Required to process eCommerce payments.

PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

POST

PUT

DELETE

Allow third party applications to deduct a portion of each transaction amount.

Required to use multiparty transaction functionality with the Transactions API.

PAYMENTS_WRITE_IN_PERSON

POST

PUT

DELETE

Grants write access to transaction and refunds information.

EXAMPLE: Required to process in-person payments.

SETTLEMENTS_READ GET

Grants read access to settlement (deposit) information.

EXAMPLE: Required to call the Connect v1 Settlements API.

TIMECARDS_READ GET

Grants read access to employee timecard information.

EXAMPLE: Required to call the the Connect v1 Timecards API.

TIMECARDS_WRITE

POST

PUT

DELETE

Grants write access to employee timecard information.

EXAMPLE: Required to create and modify timecards.

Oauth token details

An Oauth token represents the authorization a particular account has granted your application. You provide it in an Authorization header when sending requests to Square endpoints.

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 account 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 an OAuth token with the RevokeToken endpoint. Note that if an account has more than one access token for your application, this endpoint revokes all of them, regardless of which one you specify.

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.

Name Type Description
client_id string

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.

session boolean

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:

Name Type Description
response_type string

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

code string

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_token string

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_id string

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_id string

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_id string

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.

state string

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:

Name Type Description
error string

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

error_description string

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.

Name Type Description
client_id string

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

client_secret string

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

code string

The authorization code to exchange.

redirect_uri string

Optional

The redirect URL assigned in the application dashboard.

Return Value

A JSON object with the following fields:

Name Type Description
access_token string

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_type string

This value is always bearer.

expires_at string

The date when access_token expires, in ISO 8601 format.

merchant_id string

The ID of the authorizing merchant's business.

subscription_id string

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

plan_id string

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",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

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

Name Type Description
client_id string

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.

Name Type Description
access_token string

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.

Name Type Description
client_id string

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

access_token string

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_id string

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}

Mobile Authorization API

CreateMobileAuthorizationCode

POST /mobile/authorization-code

Generate a mobile authorization code for an instance of your application. Mobile authorization credentials permit an instance of your application to accept payments for a given location using the Square Reader SDK. Mobile authorization codes are one-time-use and expire shortly after being issued.

The CreateMobileAuthorizationCode endpoint accepts a JSON body.

Request Parameters

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

Name Type Description
location_id string

The location this credential should be associated with.

Return Value

A JSON object with the following format:

{
  "authorization_code": "YOUR_MOBILE_AUTHZ_CODE",
  "expires_at": "2019-01-10T19:42:08Z"
}

The value of authorization_code a generated code that permits a mobile application instance to accept payments for a given location using Square Reader SDK.

The value of expires_at indicates when your mobile authorization code expires, in ISO 8601 format.

Example Request Body

{
  "location_id": "YOUR_LOCATION_ID"
}

Authorization Data Types

CreateMobileAuthorizationCodeResponse

Represents the result of a CreateMobileAuthorizationCode request.

Fields

Name Type Description
authorization_code string

Generated code that permits an mobile application instance to accept payments for a given location using Square Reader SDK.

expires_at string

The time when the order expires if no action is taken, in ISO 8601 format.