Authorization

Build with Mobile Authorization API

Request authorization tokens to initialize Square mobile solutions like Reader SDK.

Server Side

To embed Square mobile development solutions (e.g., Reader SDK), you must create a service to request mobile authorization codes. We recommend integrating this into your existing OAuth process if possible.

Requirements and limitations

  • The Mobile Authorization API accepts requests through HTTPS and TLS 1.2. Connections through HTTP are not supported.
  • The Mobile Authorization API is not supported in the Square sandbox. See the Square Testing Guide for alternative recommendations.

Assumptions

The sample code in this guide makes the following assumptions:

  • The authorization service uses PHP version 5.4 or later. We use PHP for example code because it is a common web language and relatively approachable for new developers, but Square APIs are language agnostic and the setup steps are comparable across languages.
  • The authorization service uses the Square Connect v2 PHP SDK. Installing the SDK is optional. As long as you can package and receive JSON messages you can use Square APIs, but installing the SDK makes things easier.

Step 1: Add code to request an OAuth token

Add code to construct an OAuth request with the following permissions:

  • PAYMENTS_WRITE_IN_PERSON — required to process payments on behalf of the target Square account.
  • MERCHANT_PROFILE_READ — required to access location IDs for the target account through the Connect API.
  • PAYMENTS_READ — required to access transaction and refund details for the target account through the Connect API.
  • PAYMENTS_WRITE — required to issue refunds on behalf of the target account through the Connect API.
$applicationId = '{APPLICATION ID FOR MOBILE APP BEING AUTHORIZED}';
$squareDomain = "https://connect.squareup.com";
$oauthAuthorizePath = "/oauth2/authorize";
$mobileAuthzScope = urlencode(
                "PAYMENTS_WRITE_IN_PERSON " .
                "MERCHANT_PROFILE_READ " .
                "PAYMENTS_READ " .
                "PAYMENTS_WRITE"
              );

$authzURL = $squareDomain .
            $oauthAuthorizePath .
            "?client_id=" . $applicationId .
            "&scope=" . $mobileAuthzScope;

Make sure that the OAuth token used to obtain a mobile authorization code belongs to the Square Application used to integrate with Square mobile solutions (e.g., Reader SDK).

See the OAuth Setup Guide for more information on handling the OAuth callback and exchanging the OAuth code for a valid OAuth token.

Step 2: Get a valid location ID

  1. Use the OAuth token from Step 1 to create and configure a default API client:
// Create and configure a new Configuration object with the OAuth token
$configuration = new \SquareConnect\Configuration() ;
$configuration->setAccessToken($oauthToken) ;
$apiClient = new \SquareConnect\ApiClient($configuration) ;
  1. Create a Locations API client and select a target location:
// Create a LocationsApi client and grab the target location ID
$locClient = new \SquareConnect\Api\LocationsApi($apiClient) ;
$apiResponse = $locClient->listLocations()->getLocations() ;
foreach ($apiResponse as $location) {
  if ($location->getName() == "{TARGET LOCATION NAME}") {
    $targetLocationId = $location['id'] ;
  }
}

The code above selects a location ID based on the associated store name. Alternatively, you could present a list of locations in the browser and have the user select the location to use. For example:

<form action='{FORM SUBMISSION TARGET}' method='POST'>
  <input type='hidden' id='locationId' value=''>

<? foreach ($apiResponse as $location) { ?>
  <input
    type='submit'
    name='selectLocation'
    onclick='document.getElementById("locationId").value = "<?=$location->getId()?>"'
    value='<?=$location->getName()?>'
  ></input><br>

<? } ?>
</form>

Step 3: Request a mobile authorization code

Lastly, add code to use the location ID and OAuth token to request a mobile authorization code. The authorization service should return the mobile authorization code to the calling application but for the sake of this example, we will simply print it to the screen.

// Create a MobileAuthorizationApi client to request an authorization code
$mobileAuthzClient = new \SquareConnect\Api\MobileAuthorizationApi($apiClient) ;
$body = new \SquareConnect\Model\CreateMobileAuthorizationCodeRequest();
$body->setLocationId($targetLocationId);
$apiResponse = $mobileAuthzClient->CreateMobileAuthorizationCode($body);
$mobileCode = $apiResponse->getAuthorizationCode();

echo "Mobile authz code:" . $mobileCode;

Request a mobile authorization code with cURL

We recommend generating mobile authorization codes programmatically because they are short-lived and cannot be hardcoded and reused. But it may be necessary to generate a mobile authorization code manually during development.

To generate a mobile authorization code manually:

  1. Open the Square Application Dashboard.
  2. Copy your Personal Access Token from the Credentials page.
  3. Copy an active Location ID from the Locations page.
  4. Paste the values into the following cURL command:
curl https://connect.squareup.com/mobile/authorization-code \
  -H 'Content-Type: application/json'                       \
  -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'     \
  -d '{"location_id":"YOUR_LOCATION_ID"}'

You should get a response that looks like this:

squareup.com/mobile/authorization-code
{
  "authorization_code": "YOUR_MOBILE_AUTHORIZATION_CODE",
  "expires_at": "2018-05-11T02:05:07Z"
}

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow