Authorization

For an app to access QuickBooks Online data, the user must authorize the app. In this type of authorization, an OAuth token is used to authorize and connect an app to the company. This page describes how to use Intuit OAuth 2.0 endpoints to authorize your app’s access to your user’s QuickBooks company data when developing with the PHP SDK.

See Authentication and authorization for general information on OAuth. For reference information on the OAuth 2.0 methods, see the OAuth2 class in PHP class library reference. See the PHP OAuth 2.0 sample app for a working example of how to implement OAuth 2.0 using the PHP SDK.

The following describes how to implement OAuth 2.0 using the PHP SDK. To refresh the tokens or revoke access, see Refreshing the tokens and expiry durations and Revoking a token. To get user information, see Getting user information.

In order for the SDK to generate OAuth 2.0 tokens for the app, you must provide the necessary parameters.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<?php
use QuickBooksOnline\API\DataService\DataService;

// Prep Data Services
$dataService = DataService::Configure(array(
   'auth_mode' => 'oauth2',
   'ClientID' => "Client ID from the app's keys tab",
   'ClientSecret' => "Client Secret from the app's keys tab",
   'RedirectURI' => "The redirect URI provided on the Redirect URIs part under keys tab",
   'scope' => "com.intuit.quickbooks.accounting or com.intuit.quickbooks.payment",
   'baseUrl' => "Development/Production"
));
?>

After providing the necessary parameters, get the OAuth2LoginHelper object from the DataService object:

1
2
3

<?php
$OAuth2LoginHelper = $dataService->getOAuth2LoginHelper();
?>

The OAuth2LoginHelper object will help you complete all the necessary steps for retrieving the OAuth 2.0 tokens. First, use OAuth2LoginHelper to generate Authorization URL:

1
2
3

<?php
$authorizationUrl = $OAuth2LoginHelper->getAuthorizationCodeURL();
?>

Initialize the authentication process by presenting this URL to your customers in a browser. This must be done outside of the SDK, and cannot be completed with a script. The $authorizationCodeUrl lets your customers choose the company to connect to by clicking the Authorize button. Note that a human interaction is required at this step.

To display the authorization screen to your customers, do not use cURL. Instead, use the following in your PHP code:

1
2
3

<?php
header("Location: ".$authorizationUrl);
?>

Once a customer has authorized the app, an authorization code and realmId will be returned to the RedirectURI you specified previously as query parameters. Provide these parameters the exchangeAuthorizationCodeForToken method to exchange for OAuth 2 tokens:

1
2
3

<?php
$accessTokenObj = $OAuth2LoginHelper->exchangeAuthorizationCodeForToken("authorizationCode", "RealmId");
?>

The $accessTokenObj object contains both the access token and refresh token.

After the above steps, the OAuth 2 token generation is complete.

If you want to use the access token and refresh token directly for your application, update the DataService object and the app is ready to make API calls using OAuth 2 tokens:

1
2
3

<?php
$dataService->updateOAuth2Token($accessTokenObj);
?>

To store either the refresh token or the access token to your own database, you can use the following to get the OAuth 2 Access Token value:

1
2
3

<?php
$accessTokenValue = $accessTokenObj->getAccessToken();
?>

To get the OAuth 2 Refresh Token value:

1
2
3

<?php
$refreshTokenValue = $accessTokenObj->getRefreshToken();
?>

You should always store your OAuth 2 refresh token to your own session or database.

Once the tokens are received, you can then make QuickBooks Online API calls using the PHP SDK. If you have already retrieved OAuth 2 tokens, simply provide them to the DataService object. This is very similar to OAuth 1.0a: simply change the auth_mode parameter from “oauth1” to “oauth 2”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<?php
use QuickBooksOnline\API\DataService\DataService;

// Prep Data Services
$dataService = DataService::Configure(array(
   'auth_mode' => 'oauth2',
   'ClientID' => "Client ID from the app's keys tab",
   'ClientSecret' => "Client Secret from the app's keys tab",
   'accessTokenKey' => 'OAuth 2 Access Token',
   'refreshTokenKey' => "OAuth 2 Refresh Token",
   'QBORealmId' => "The Company ID which the app wants to access",
   'baseUrl' => "Development/Production"
));
?>

The PHP SDK uses the Mozilla CA certificates (https://curl.haxx.se/ca/cacert.pem) for authorizing peer certificates.

To disable the cURL certificate settings from PHP SDK, comment out line 106 of the cURL HTTP (CurlHttpClient) or append your self-signed certificate in cacert.pem.

Because an OAuth 2 access token is only valid for one hour, you often need to use the refresh token to request a new access token.

To refresh your OAuth 2 access token, pass your Client ID, Client Secret, OAuth 2 refresh token, realmId, and baseURL to the $dataService object, then use $OAuth2LoginHelper to request a new refresh token:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<?php
use QuickBooksOnline\API\DataService\DataService;

// Prep Data Services
$dataService = DataService::Configure(array(
'auth_mode' => 'oauth2',
'ClientID' => "Client ID from the app's keys tab",
'ClientSecret' => "Client Secret from the app's keys tab",
// Get the refresh token from session or database
'refreshTokenKey' => "Your latest OAuth 2 Refresh Token",
'QBORealmId' => "The Company ID which the app wants to access",
'baseUrl' => "Development/Production"
));

$OAuth2LoginHelper = $dataService->getOAuth2LoginHelper();
$refreshedAccessTokenObj = $OAuth2LoginHelper->refreshToken();
$error = $OAuth2LoginHelper->getLastError();
if($error){
...
} else {
//Refresh Token is called successfully
$dataService->updateOAuth2Token($refreshedAccessTokenObj);
...
}
?>

After PHP SDK v4.0.5 release, you can direcly construct OAuth2LoginHelper and use the refreshAccessTokenWithRefreshToken method to refresh the token:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

<?php
require 'vendor/autoload.php';

use QuickBooksOnline\API\Core\OAuth\OAuth2\OAuth2LoginHelper;

// The first parameter of OAuth2LoginHelper is the ClientID, second parameter is the client Secret
$oauth2LoginHelper = new OAuth2LoginHelper("replace-with-client-id","replace-with-client-secret");
$accessTokenObj = $oauth2LoginHelper->
   refreshAccessTokenWithRefreshToken("replace-with-token-value");
$accessTokenValue = $accessTokenObj->getAccessToken();
$refreshTokenValue = $accessTokenObj->getRefreshToken();
echo "Access Token is:";
print_r($accessTokenValue);
echo "RefreshToken Token is:";
print_r($refreshTokenValue);
?>

For each new OAuth 2 access token and OAuth 2 refresh token returned from QuickBooks Online, you will need to use the getRefreshToken() method to get the latest refresh token.

For a complete example of how to refresh the OAuth token, see refreshTokenSample on GitHub.

To revoke the access or refresh tokens and invalidate access, use the revokeToken($accessTokenOrRefreshToken) method in the OAuth2LoginHelper class. The following example revokes the Refresh token:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<?php

require 'vendor/autoload.php';

use QuickBooksOnline\API\Core\OAuth\OAuth2\OAuth2LoginHelper;

//The first parameter of OAuth2LoginHelper is the ClientID, second parameter is the client Secret
$oauth2LoginHelper = new OAuth2LoginHelper("replace-with-client-id","replace-with-client-secret");
$revokeResult = $oauth2LoginHelper->
revokeToken("replace-with-token-value");
if($revokeResult){
echo "RefreshToken Token revoked.";
}
?>

To get user information, use the callForOpenIDEndpoint() method, which gets minimal user information details when the OpenId scope is set. Additional details–such as email, profile, phone, or address–for a user can be obtained if those scopes are set. The following example gets the user information:

1
2
3

<?php
$userInfo = $client->callForOpenIDEndpoint($openID_accessToken, $usrInfoURL);
?>