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

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.

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

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

Name Description
client_id
string

Required

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

Max Length 191
client_secret
string

Required

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

Min Length 2 Max Length 1024
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.

Max Length 191
redirect_uri
string

The redirect URL assigned in the application 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 the application wants a replacement for an expired OAuth access token.

Min Length 2 Max Length 1024
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.

Min Length 2 Max Length 1024
scopes
string [ ]

Beta

OPTIONAL

A JSON list of strings representing the permissions 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

Beta

OPTIONAL

A boolean indicating a request for a short-lived access token. The short-lived access token returned in the response will expire in 24 hours.

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. See OAuth API: Walkthrough for more information.

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

plan_id
string

LEGACY FIELD. 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. OAuth refresh tokens are 64 bytes long. For more information, see OAuth access token management.

Min Length 2 Max Length 1024
short_lived
boolean

Beta

A boolean indicating the access token is a short-lived access token. The short-lived access token returned in the response will expire in 24 hours.

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: 2021-03-17' \
  -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"
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?