Walkthrough: Obtaining an Access Token in the Square Sandbox

This walkthrough provides quick steps to generate a test OAuth token. A best practice is to use a web server to receive the seller authorization. To keep the walkthrough as simple as possible, the redirect URL indicates a callback that is not implemented. You simply let the callback page not be found and use the returned URL that contains the code value you need. For a deeper discussion of the OAuth process, see:

To create a Sandbox OAuth access token:

  1. Sign in to the Developer Dashboard using your developer account.

  2. On the Applications page, scroll down to the Sandbox Test Accounts section and choose Add.

    1. In the Account Name box, enter Seller Test Account.

    2. In the Country box, choose any country.

    3. Clear the Automatically create authorizations for all my current apps checkbox.

    4. Choose Create.

  3. Open your application and choose OAuth in the left pane. Set the Sandbox Redirect URL to http://localhost:8080/callback.

    1. Copy the Sandbox Application ID and Sandbox Application secret values; you use these values in the following steps.

    2. Choose Save.

  4. On the Applications page, go to the Sandbox Test Accounts section and choose Open for the Seller Test Account. The Seller Dashboard opens in a new window.

  5. Open a new tab in the same browser and do the following:

    1. Paste the following URL in the URL address. Replace sandbox-application-ID in the URL with the Sandbox application ID you copied in step 3 and then press Enter.

    2. When a window opens, choose Allow to grant the developer account the requested permissions.

  6. Square returns a URL with the code you used to get an access token. Because you are not using a web server page to retrieve the URL, the page shows This site can’t be reached. The response URL in the URL address box contains the code you need.

  7. Copy the code value. You use this value to obtain an access token with the requested permissions using the ObtainToken command. In the following example, replace ```, <application-id>, and <application-secret> with the code, Sandbox application ID, and Sandbox application secret, respectively. Run the following ObtainToken command to obtain an OAuth access token:

    curl https://connect.squareupsandbox.com/oauth2/token \ -X POST \ -H 'Square-Version: 2022-03-16' \ -H 'Content-Type: application/json' \ -d '{ "grant_type": "authorization_code", "code": "`", "client_id": "<application-id>", "client_secret": "<application-secret>" }' | jq

    The following is an example of the JSON response:

    { "access_token": "EAAAEJ0z0nN9cRt3HEPByaX-jT6mPdZFEFerycDL46eHla2lE-F3TexWQH1EG1_", "token_type": "bearer", "expires_at": "2022-06-14T19:30:31Z", "merchant_id": "MLS1XCNYHK3QQ", "refresh_token": "EQAAEBocG3WhN6Xn3ntcfqAMHeJMDUA4HBYLPSt7QXwfXLn7T7K3VoEVlFhLuhaO", "short_lived": false }

    You can now use the access token to perform permitted actions on behalf of the seller.


This walkthrough is an example of how you obtain an OAuth access token using a Sandbox test account. It is similar to the process you use in production. If you want to have Sandbox test accounts authorized without having to use this process, leave the Automatically create authorizations for all my current apps checkbox selected when you create a new Sandbox test account.

Link to section

Related topics