Obtain 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_
Required
|
The Square-issued ID of your application, available from the application dashboard. |
client_
Required
|
The Square-issued application secret for your application, available from the application dashboard. |
code
|
The authorization code to exchange.
This is required if |
redirect_
|
The redirect URL assigned in the application dashboard. |
grant_
Required
|
Specifies the method to request an OAuth access token.
Valid values are: |
refresh_
|
A valid refresh token for generating a new OAuth access token.
A valid refresh token is required if |
migration_
|
Legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if |
scopes
Beta
|
OPTIONAL A JSON list of strings representing the permissions the application is requesting.
For example: " |
short_
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_
|
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. |
token_
|
This value is always bearer. |
expires_
|
The date when access_token expires, in ISO 8601 format. |
merchant_
|
The ID of the authorizing merchant's business. |
subscription_
|
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_
|
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_
|
Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request. |
refresh_
|
A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see OAuth access token management. |
short_
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
- 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"
}'
{
"access_token": "ACCESS_TOKEN",
"token_type": "bearer",
"expires_at": "2006-01-02T15:04:05Z",
"merchant_id": "MERCHANT_ID",
"refresh_token": "REFRESH_TOKEN"
}