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

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.

client_secret
string

Required

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
string

Required

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

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

Examples

You are viewing an old version of the API
POST /oauth2/token
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -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?