Obtain token
Returns an OAuth access token and a refresh token unless the
short_lived
parameter is set to true
, in which case the endpoint
returns only an access token.
The grant_type
parameter specifies the type of OAuth request. If
grant_type
is authorization_code
, you must include the authorization
code you received when a seller granted you authorization. If grant_type
is refresh_token
, you must provide a valid refresh token. If you are using
an old version of the Square APIs (prior to March 13, 2019), grant_type
can be migration_token
and you must provide a valid migration token.
You can use the scopes
parameter to limit the set of permissions granted
to the access token and refresh token. You can use the short_lived
parameter
to create an access token that expires in 24 hours.
Note: OAuth tokens should be encrypted and stored on a secure server. Application clients should never interact directly with OAuth tokens.
Name | Description |
---|---|
client_
Required
|
The Square-issued ID of your application, which is available in the OAuth page in the Developer Dashboard. |
client_
Required
|
The Square-issued application secret for your application, which is available in the OAuth page in the Developer Dashboard. |
code
|
The authorization code to exchange.
This code is required if |
redirect_
|
The redirect URL assigned in the OAuth page for your application in the Developer 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_
|
A legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if |
scopes
Beta
|
A JSON list of strings representing the permissions that the application is requesting.
For example, " 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_
Beta
|
A Boolean indicating a request for a short-lived access token. The short-lived access token returned in the response expires 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. For more information, see OAuth API: Walkthrough. |
token_
|
This value is always bearer. |
expires_
|
The date when the |
merchant_
|
The ID of the authorizing merchant's business. |
subscription_
|
LEGACY FIELD. The ID of a subscription plan the merchant signed up for. The ID is only present if the merchant signed up for a subscription plan during authorization. |
plan_
|
LEGACY FIELD. The ID of the subscription plan the merchant signed up for. The ID is only present if the merchant signed up for a subscription plan during authorization. |
id_
Deprecated
|
The OpenID token belonging to this person. This token is only present if the OPENID scope is included in the authorization request. |
refresh_
|
A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see Refresh, Revoke, and Limit the Scope of OAuth Tokens. |
short_
Beta
|
A Boolean indicating that the access token is a short-lived access token. The short-lived access token returned in the response expires in 24 hours. |
errors
|
Any errors that occurred during the request. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/oauth2/token \
-X POST \
-H 'Square-Version: 2022-06-16' \
-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"
}