Authorization API Reference

Authorization Basics

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 the Square Permission Request form to start the OAuth access token workflow for this purpose. OAuth access tokens are ASCII strings no greater than 64 bytes in length. OAuth access tokens are scoped to specific permissions explicitly granted by the account holder.

alt text

Authorize endpoint

To send users to the Permission Request form and start the OAuth flow, configure a link with the desired permissions that directs users to the OAuth Authorization endpoint. See the OAuth Setup Guide for more information.

GET /oauth2/authorize

Request parameters

Name Type Description
client_id string The Square-issued ID of the application requesting permissions.
scope string Optional. A space-separated list of the permissions the application is requesting.

Default: MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ
locale string Optional. The locale to present the permission request form in. Square detects the appropriate locale automatically. Only provide this value if the application can definitively determine the preferred locale. Currently supported values: en-US, en-CA, es-US, fr-CA, ja-JP.
session boolean If false, the user must log in to their Square account to view the Permission Request form, even if they already have a valid user session.

Default: true
state string Optional. When provided, state is passed along to the configured Redirect URL after the Permission Request form is submitted. You can include state and verify its value to help protect against cross-site request forgery.

Authorization response

When users submit the Permissions form, the Square OAuth server calls back to the configured redirect URL. The parameters included in the URL depend on whether authorization succeeded.

Success response

If authorization succeedes, the Authorize response includes the following:

Name Type Description
code string A valid authorization code. Authorization codes are exchanged for OAuth access tokens with the ObtainToken endpoint.
state string The same value specified in the request.

Failure response

If authorization fails (e.g., the user denied access, an error occurred), the Authorize response includes the following:

Name Type Description
error string The type of error that occurred. If the user denied access, this value is access_denied.
error_description string The reason the error occurred. If the user denied access, this value is user_denied.

Authorization APIs

If Square API endpoints receive too many requests associated with the same application ID or access token in a short time window, they might respond with a 429 Too Many Requests error, indicating that the application may try the request again at a later time.

CreateMobileAuthorizationCode

POST /mobile/authorization-code

Generates code to authorize a mobile application to connect to a Square card reader

Authorization codes are one-time-use and expire 60 minutes after being issued.

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

Authorization: Bearer ACCESS_TOKEN

Replace ACCESS_TOKEN with a valid production authorization credential.

Required permissions: PAYMENTS_WRITE_IN_PERSON

Body Parameters

Name Type Description
location_id string

The Square location ID the authorization code should be tied to.

Response fields

Name Type Description
authorization_code string

Generated authorization code that connects a mobile application instance to a Square account.

expires_at string

The timestamp when authorization_code expires in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

error Error

An error object that provides details about how creation of authorization code failed.

Example Request

POST /mobile/authorization-code

{
  "location_id": "YOUR_LOCATION_ID"
}

Example Response

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

ObtainToken

POST /oauth2/token

Returns an OAuth access token.

The endpoint supports distinct methods of obtaining OAuth access tokens. Applications specify a method by adding the grant_type parameter in the request and also provide relevant information. For more information, see OAuth access token management.

Note: Regardless of the method application specified, the endpoint always returns two items; an OAuth access token and a refresh token in the response.

By default, the OAuth API lets up to 500 Square accounts authorize your application. Please contact support if you are developing an application for a larger audience.

OAuth tokens should only live on secure servers. Application clients should never interact directly with OAuth tokens.

Body Parameters

Name Type Description
client_id
(required)
string

The Square-issued ID of your application, available from the application dashboard.

client_secret
(required)
string

The Square-issued application secret for your application, available from the application dashboard.

code string

The authorization code to exchange. This is required if grant_type is set to authorization_code, to indicate that the application wants to exchange an authorization code for an OAuth access token.

redirect_uri string

The redirect URL assigned in the application dashboard.

grant_type
(required)
string

Specifies the method to request an OAuth access token. Valid values are: authorization_code, refresh_token, and migration_token

refresh_token string

A valid refresh token for generating a new OAuth access token. A valid refresh token is required if grant_type is set to refresh_token , to indicate the application wants a replacement for an expired OAuth access token.

migration_token string

Legacy OAuth access token obtained using a Connect API version prior to 2019-03-13. This parameter is required if grant_type is set to migration_token to indicate that the application wants to get a replacement OAuth access token. The response also returns a refresh token. For more information, see Migrate to Using Refresh Tokens.

Response fields

Name Type Description
access_token string

A valid OAuth access token. OAuth access tokens are 64 bytes long. Provide the access token in a header with every request to Connect API endpoints. See the Build with OAuth guide for more information.

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

Legacy field. The ID of a subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.

plan_id string

The ID of the subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.

id_token string

Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request.

refresh_token string

A refresh token. For more information, see OAuth access token management.

Example Request

POST /oauth2/token

{
  "client_id": "APPLICATION_ID",
  "client_secret": "APPLICATION_SECRET",
  "code": "CODE_FROM_AUTHORIZE"
}

Example Response

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2006-01-02T15:04:05Z",
  "merchant_id": "MERCHANT_ID"
}

RenewToken DEPRECATED

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

RenewToken is deprecated. For information about refreshing OAuth access tokens, see Renew OAuth Token.

Renews an OAuth access token before it expires.

OAuth access tokens besides your application's personal access token expire after 30 days. 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 user must re-complete the OAuth flow from the beginning.

Important: The Authorization header for this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with the application secret on the Credentials page in the application dashboard.

Path Parameters

Name Type Description
client_id
(required)
string

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

Body Parameters

Name Type Description
access_token string

The token you want to renew.

Response fields

Name Type Description
access_token string

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.

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. Only present if the merchant signed up for a subscription during authorization.

plan_id string

The ID of the subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.

Example Request

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

{
  "access_token": "ACCESS_TOKEN"
}

Example Response

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2006-01-02T15:04:05Z",
  "merchant_id": "MERCHANT_ID"
}

RevokeToken

POST /oauth2/revoke

Revokes an access token generated with the OAuth flow.

If an account has more than one OAuth access token for your application, this endpoint revokes all of them, regardless of which token you specify. When an OAuth access token is revoked, all of the active subscriptions associated with that OAuth token are canceled immediately.

Important: The Authorization header for this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with the application secret on the Credentials page in the application dashboard.

Body Parameters

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.

Response fields

Name Type Description
success boolean

If the request is successful, this is true.

Example Request

POST /oauth2/revoke

{
  "access_token": "ACCESS_TOKEN",
  "client_id": "CLIENT_ID"
}

Example Response

{
  "success": true
}

API Data Types

Error

Represents an error encountered during a request to the Connect API.

Fields

Name Type Description
category string

The error's high-level category. See ErrorCategory for possible values

code string

The error's specific code. See ErrorCode for possible values

detail string

A human-readable description of the error for debugging purposes.

field string

The name of the field provided in the original request that the error pertains to, if any.

API Enums

Some Square API enums include the value OTHER. Responses that currently include the value OTHER might have a different value at a later date, when an appropriate value has been added to the enum. Enum values besides OTHER never change retroactively.

ErrorCategory

Indicates which high-level category of error has occurred during a request to the Connect API.

Fields

Name Description
API_ERROR

An error occurred with the Connect API itself.

AUTHENTICATION_ERROR

An authentication error occurred. Most commonly, the request had a missing, malformed, or otherwise invalid Authorization header.

INVALID_REQUEST_ERROR

The request was invalid. Most commonly, a required parameter was missing, or a provided parameter had an invalid value.

RATE_LIMIT_ERROR

Your application reached the Connect API rate limit. Retry your request after a while.

PAYMENT_METHOD_ERROR

An error occurred while processing a payment method. Most commonly, the details of the payment method were invalid (such as a card's CVV or expiration date).

REFUND_ERROR

An error occurred while attempting to process a refund.

ErrorCode

Indicates specific errors that can occur during a request to the Connect API.

Fields

Name Description
INTERNAL_SERVER_ERROR
UNAUTHORIZED
ACCESS_TOKEN_EXPIRED
ACCESS_TOKEN_REVOKED
FORBIDDEN
INSUFFICIENT_SCOPES
APPLICATION_DISABLED
V1_APPLICATION
V1_ACCESS_TOKEN
CARD_PROCESSING_NOT_ENABLED
BAD_REQUEST
MISSING_REQUIRED_PARAMETER
INCORRECT_TYPE
INVALID_TIME
INVALID_TIME_RANGE
INVALID_VALUE
INVALID_CURSOR
UNKNOWN_QUERY_PARAMETER
CONFLICTING_PARAMETERS
EXPECTED_JSON_BODY
INVALID_SORT_ORDER
VALUE_REGEX_MISMATCH
VALUE_TOO_SHORT
VALUE_TOO_LONG
VALUE_TOO_LOW
VALUE_TOO_HIGH
VALUE_EMPTY
ARRAY_LENGTH_TOO_LONG
ARRAY_LENGTH_TOO_SHORT
ARRAY_EMPTY
EXPECTED_BOOLEAN
EXPECTED_INTEGER
EXPECTED_FLOAT
EXPECTED_STRING
EXPECTED_OBJECT
EXPECTED_ARRAY
EXPECTED_MAP
EXPECTED_BASE64_ENCODED_BYTE_ARRAY
INVALID_ARRAY_VALUE
INVALID_ENUM_VALUE
INVALID_CONTENT_TYPE
INVALID_FORM_VALUE
ONE_INSTRUMENT_EXPECTED
NO_FIELDS_SET
DEPRECATED_FIELD_SET
CARD_EXPIRED
INVALID_EXPIRATION
INVALID_EXPIRATION_YEAR
INVALID_EXPIRATION_DATE
UNSUPPORTED_CARD_BRAND
UNSUPPORTED_ENTRY_METHOD
INVALID_ENCRYPTED_CARD
INVALID_CARD
DELAYED_TRANSACTION_EXPIRED
DELAYED_TRANSACTION_CANCELED
DELAYED_TRANSACTION_CAPTURED
DELAYED_TRANSACTION_FAILED
CARD_TOKEN_EXPIRED
CARD_TOKEN_USED
AMOUNT_TOO_HIGH
UNSUPPORTED_INSTRUMENT_TYPE
REFUND_AMOUNT_INVALID
REFUND_ALREADY_PENDING
PAYMENT_NOT_REFUNDABLE
INVALID_CARD_DATA
LOCATION_MISMATCH
IDEMPOTENCY_KEY_REUSED
UNEXPECTED_VALUE
SANDBOX_NOT_SUPPORTED
INVALID_EMAIL_ADDRESS
INVALID_PHONE_NUMBER
CHECKOUT_EXPIRED
BAD_CERTIFICATE
INVALID_SQUARE_VERSION_FORMAT
API_VERSION_INCOMPATIBLE
CARD_DECLINED
VERIFY_CVV_FAILURE
VERIFY_AVS_FAILURE
CARD_DECLINED_CALL_ISSUER
NOT_FOUND
APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
METHOD_NOT_ALLOWED
NOT_ACCEPTABLE
REQUEST_TIMEOUT
CONFLICT
REQUEST_ENTITY_TOO_LARGE
UNSUPPORTED_MEDIA_TYPE
RATE_LIMITED
NOT_IMPLEMENTED
SERVICE_UNAVAILABLE
GATEWAY_TIMEOUT

OAuthPermission

When you direct your user to the permissions form, you specify the scope of the permissions your application will have. Personal access tokens have all available permissions (at the time the application was created) by default.

Fields

Name Description
BANK_ACCOUNTS_READ

HTTP Method: GET

Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.

CUSTOMERS_READ

HTTP Method: GET

Grants read access to customer information. For example, to call the ListCustomers endpoint.

CUSTOMERS_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to customer information. For example, to create and update customer profiles.

EMPLOYEES_READ

HTTP Method: GET

Grants read access to employee profile information. For example, to call the Connect v1 Employees API.

EMPLOYEES_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to employee profile information. For example, to create and modify employee profiles.

INVENTORY_READ

HTTP Method: GET

Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.

INVENTORY_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.

ITEMS_READ

HTTP Method: GET

Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.

ITEMS_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to product catalog information. For example, to modify or add to a product catalog.

MERCHANT_PROFILE_READ

HTTP Method: GET

Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.

ORDERS_READ

HTTP Method: GET

Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.

ORDERS_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to order information. For example, to call the CreateCheckout endpoint.

PAYMENTS_READ

HTTP Method: GET

Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.

PAYMENTS_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to transaction and refunds information. For example, to process payments with the Transactions or Checkout API.

PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

HTTP Method: 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

HTTP Method: POST, PUT, DELETE

Grants write access to transaction and refunds information. For example, to process in-person payments.

SETTLEMENTS_READ

HTTP Method: GET

Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.

TIMECARDS_READ

HTTP Method: GET

Grants read access to employee timecard information. For example, to call the Connect v1 ListTimecards endpoint.

TIMECARDS_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to employee timecard information. For example, to create and modify timecards.

TIMECARDS_SETTINGS_READ

HTTP Method: GET

Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.

TIMECARDS_SETTINGS_WRITE

HTTP Method: POST, PUT, DELETE

Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.

Common OAuth errors

Invalid client or client secret

Likely cause

An incorrect application secret was provided in a request to the endpoint.

Solution

Confirm you have copied the entirety of your application secret from the Credentials page in the application dashboard.

Invalid code

Likely cause

An incorrect authorization code was provided in a request to the ObtainToken endpoint.

Solution

Confirm that the authorization code matches the value provided to your Redirect URL. Additionally, it may have been long enough since the authorization code was issued that it has expired. In this case, return to the OAuth Authorize endpoint to generate a new authorization code and try again.

Unauthorized

Likely cause

In most cases, an incorrect access token was provided in the header of a request to a Connect API endpoint.

Solution

Confirm the provided access token is valid for the application and, if you are using REST, that it is provided in an HTTP header with the following format:

Authorization: Bearer ACCESS_TOKEN