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.

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.

Guide

Authorizing an application and obtaining 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 developer dashboard. Max Length 191
`client_secret string` Required	The Square-issued application secret for your application, available from the developer 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 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 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	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	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

POST /oauth2/token

curl https://connect.squareup.com/oauth2/token \
  -X POST \
  -H 'Square-Version: 2021-07-21' \
  -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 2021-07-21 Version 2021-07-21 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