• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Obtain token

POST /oauth2/token

Returns an OAuth access token and a refresh token unless the short_lived parameter is set to true, in which case the endpoint returns only an access token.

The grant_type parameter specifies the type of OAuth request. If grant_type is authorization_code, you must include the authorization code you received when a seller granted you authorization. If grant_type is refresh_token, you must provide a valid refresh token. If you are using an old version of the Square APIs (prior to March 13, 2019), grant_type can be migration_token and you must provide a valid migration token.

You can use the scopes parameter to limit the set of permissions granted to the access token and refresh token. You can use the short_lived parameter to create an access token that expires in 24 hours.

Note: OAuth tokens should be encrypted and stored on a secure server. Application clients should never interact directly with OAuth tokens.

Guide
Receive Seller Authorization and Manage Seller OAuth Tokens Try in API Explorer

Request Body

Example code
Name Description
client_id
string
Required

The Square-issued ID of your application, which is available in the OAuth page in the Developer Dashboard.

Max Length 191
client_secret
string

The Square-issued application secret for your application, which is available in the OAuth page in the Developer Dashboard. This parameter is only required when you are not using the OAuth PKCE (Proof Key for Code Exchange) flow. The PKCE flow requires a code_verifier instead of a client_secret.

Min Length 2 Max Length 1024
code
string

The authorization code to exchange. This code 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.

Max Length 191
redirect_uri
string

The redirect URL assigned in the OAuth page for your application in the Developer Dashboard.

Max Length 2048
grant_type
string
Required

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

Min Length 10 Max Length 20
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 that the application wants a replacement for an expired OAuth access token.

Min Length 2 Max Length 1024
migration_token
string

A 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.

Min Length 2 Max Length 1024
scopes
string [ ]

A JSON list of strings representing the permissions that the application is requesting. For example, "["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]".

The access token returned in the response is granted the permissions that comprise the intersection between the requested list of permissions and those that belong to the provided refresh token.
short_lived
boolean

A Boolean indicating a request for a short-lived access token.

The short-lived access token returned in the response expires in 24 hours.
code_verifier
string
Beta

Must be provided when using PKCE OAuth flow. The code_verifier will be used to verify against the code_challenge associated with the authorization_code.

Response Fields
Name 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. For more information, see OAuth API: Walkthrough.

Min Length 2 Max Length 1024
token_type
string

This value is always bearer.

Min Length 2 Max Length 10
expires_at
string

The date when the access_token expires, in ISO 8601 format.

Min Length 20 Max Length 48
merchant_id
string

The ID of the authorizing merchant's business.

Min Length 8 Max Length 191
subscription_id
string

LEGACY FIELD. The ID of a subscription plan the merchant signed up for. The ID is only present if the merchant signed up for a subscription plan during authorization.
plan_id
string

LEGACY FIELD. The ID of the subscription plan the merchant signed up for. The ID is only present if the merchant signed up for a subscription plan during authorization.
id_token
string
Deprecated

The OpenID token belonging to this person. This token is only present if the OPENID scope is included in the authorization request.
refresh_token
string

A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see Refresh, Revoke, and Limit the Scope of OAuth Tokens.

Min Length 2 Max Length 1024
short_lived
boolean

A Boolean indicating that the access token is a short-lived access token. The short-lived access token returned in the response expires in 24 hours.
errors
Error [ ]

Any errors that occurred during the request.
refresh_token_expires_at
string

The date when the refresh_token expires, in ISO 8601 format.

Min Length 20 Max Length 48

Examples

You are viewing an old version of the API
POST /oauth2/token
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "APPLICATION_ID",
    "client_secret": "APPLICATION_SECRET",
    "code": "CODE_FROM_AUTHORIZE",
    "grant_type": "authorization_code"
  }'
Response JSON 
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_at": "2006-01-02T15:04:05Z",
  "merchant_id": "MERCHANT_ID",
  "refresh_token": "REFRESH_TOKEN"
}