Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-142008071.1 MB
OAuth

ObtainToken

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.

post/oauth2/token

Request body

client_idstring required

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

client_secretstring required

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

codestring

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.

grant_typestring required

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

migration_tokenstring

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.

redirect_uristring

The redirect URL assigned in the developer dashboard.

refresh_tokenstring

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.

scopesstring[]

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_livedboolean

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.

Example request

{
  "request_body": {
    "client_id": "APPLICATION_ID",
    "client_secret": "APPLICATION_SECRET",
    "code": "CODE_FROM_AUTHORIZE",
    "grant_type": "authorization_code"
  }
}

Response

Success

access_tokenstring

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.

expires_atstring

The date when access_token expires, in ISO 8601 format.

id_tokenstring

Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request.

merchant_idstring

The ID of the authorizing merchant's business.

plan_idstring

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.

refresh_tokenstring

A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see OAuth access token management.

short_livedboolean

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.

subscription_idstring

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.

token_typestring

This value is always bearer.

Example response

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