You are viewing an old version of the API

All Versions

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.

Try in API Explorer

Request Body

Example code

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

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"
  }'

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

OAuth API You are viewing an old version of the API 2020-09-23 Version 2020-09-23 All Versions OAuth API Obtain token

Request Body

Response Fields

Examples

Share Feedback

You are viewing an old version of the API

All Versions

Obtain token