<- OAuth API

OAuth API

Obtain token

POST

 /oauth2/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're 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.

Guide

Receive Seller Authorization and Manage Seller OAuth Tokens

Try in API Explorer
Link to section

Request body

Example code

Link to section

client_id

string

Required

The Square-issued ID of your application, which is available on the OAuth page in the Developer Dashboard.

Max Length
191
Link to section

client_secret

string

The Square-issued application secret for your application, which is available on the OAuth page in the Developer Dashboard. This parameter is only required when you're not using the OAuth PKCE (Proof Key for Code Exchange) flow. The PKCE flow requires a code_verifier instead of a client_secret when grant_type is set to authorization_code. If grant_type is set to refresh_token and the refresh_token is obtained uaing PKCE, the PKCE flow only requires client_id, grant_type, and refresh_token.

Min Length
2
Max Length
1024
Link to section

code

string

The authorization code to exchange. This code 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
Link to section

redirect_uri

string

The redirect URL assigned on the OAuth page for your application in the Developer Dashboard.

Max Length
2048
Link to section

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
Link to section

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 that the application wants a replacement for an expired OAuth access token.

Min Length
2
Max Length
1024
Link to section

migration_token

string

A 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
Link to section

scopes

string [ ]

A JSON list of strings representing the permissions that 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.

Link to section

short_lived

boolean

A Boolean indicating a request for a short-lived access token.

The short-lived access token returned in the response expires in 24 hours.

Link to section

code_verifier

string

Must be provided when using the PKCE OAuth flow if grant_type is set to authorization_code. The code_verifier is used to verify against the code_challenge associated with the authorization_code.

Link to section

Response fields

Link to section

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. For more information, see OAuth API: Walkthrough.

Min Length
2
Max Length
1024
Link to section

token_type

string

This value is always bearer.

Min Length
2
Max Length
10
Link to section

expires_at

string

The date when the access_token expires, in ISO 8601 format.

Min Length
20
Max Length
48
Link to section

merchant_id

string

The ID of the authorizing merchant's business.

Min Length
8
Max Length
191
Link to section

subscription_id

string

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.

Link to section

plan_id

string

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.

Link to section

id_token

string

Deprecated

The OpenID token belonging to this person. This token is only present if the OPENID scope is included in the authorization request.

Link to section

refresh_token

string

A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see Refresh, Revoke, and Limit the Scope of OAuth Tokens.

Min Length
2
Max Length
1024
Link to section

short_lived

boolean

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.

Link to section

errors

Any errors that occurred during the request.

Link to section

refresh_token_expires_at

string

The date when the refresh_token expires, in ISO 8601 format.

Min Length
20
Max Length
48