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 Java SDK.

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

Authorizing your app

The following describes how to implement OAuth 2.0 and the details of the validation sequence using the Java 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.

Generate the Authorization URL

To generate the authorization URL, do the following:


You can use the methods provided in the SDK to obtain the OAuth 2.0 tokens, or call the discovery endpoint directly to obtain the tokens. To use the SDK methods, prepare the configuration by setting the discovery environment for sandbox or production to get the OAuth2 endpoint URLs from the discovery document, and build the configuration using the OAuth2ConfigBuilder() method of the OAuth2Config class. To get the tokens using the SDK, call the Discovery API while preparing the OAuth2Config object. Each of the steps to get the authorization URL are shown below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder(
   "OAuth2AppClientId",
   "OAuth2AppClientSecret"
) // set client id and secret
   .callDiscoveryAPI(Environment.SANDBOX) // call discovery API to populate urls
   .buildConfig();

//Generate the CSRF token
String csrf = oauth2Config.generateCSRFToken();

//Prepare scopes
List<Scope> scopes = new ArrayList<Scope>();
scopes.add(Scope.OpenIdAll);
scopes.add(Scope.Accounting); // add as needed

//Get the authorization URL
String url = oauth2Config.prepareUrl(scopes, redirectUri, csrf); //redirectUri - pass the callback url

If you choose to call the Discovery endpoint directly, use the following code and use the URLs from the response object to make the OAuth 2.0 calls separately. The Environment parameter allows you to set the Discovery API for sandbox or production. Set the Discovery API for sandbox as follows:

1
DiscoveryAPIResponse discoveryAPIResponse = new DiscoveryAPIClient().callDiscoveryAPI(Environment.SANDBOX);

To call the Discovery API for production:

1
DiscoveryAPIResponse discoveryAPIResponse = new DiscoveryAPIClient().callDiscoveryAPI(Environment.PRODUCTION);
Get the tokens and expiry details

To get the tokens and expiry details, handle the response in the callback endpoint. To retrieve the bearer token, send the authorization code and redirect URL to the retrieveBearerTokens() method, then use getAccessToken() to get the access token as shown in the following example:

1
2
3
4
5
//Prepare OAuth2PlatformClient
OAuth2PlatformClient client  = new OAuth2PlatformClient(oauth2Config);

//Get the bearer token (OAuth2 tokens)
BearerTokenResponse bearerTokenResponse = client.retrieveBearerTokens(authCode, redirectUri);

Next, retrieve the access and refresh tokens using getAccessToken() and getRefreshToken() as follows:

1
2
bearerTokenResponse.getAccessToken()
bearerTokenResponse.getRefreshToken()
For OpenID, validate the ID token

For OpenID scopes, validate the ID token as follows:

1
boolean valid = client.validateIDToken(bearerTokenResponse.getIdToken())
Calling the QuickBooks Online API

The information required for authorization is passed using a Context object. An instance of the Context can be initialized by creating an OAuth2Authorizer object. In this type of authorization, the OAuth2Authorizer object uses an OAuth token to authorize and connect an app to the QuickBooks company. The following example creates the OAuth object and context, then creates the DataService object and makes a QuickBooks Online API call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Create OAuth object
OAuth2Authorizer oauth = new OAuth2Authorizer("accessToken"); //set access token obtained from BearerTokenResponse

// Create context
Context context = new Context(oauth, ServiceType.QBO, "realmId"); //set realm id

// Create dataservice
DataService service = new DataService(context);

// Make the API call
String sql = "select * from companyinfo";
QueryResult queryResult = service.executeQuery(sql);
Refreshing the tokens and expiry durations

After the app receives the authorization code, it exchanges the authorization code for refresh and access tokens. Retrieve the base URI from the discovery document. Your app must keep track of when a stored access token can be used and when the token must be refreshed. Use the refreshToken() method to refresh the token as shown in the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
//Prepare config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder(
   "OAuth2AppClientId",
   "OAuth2AppClientSecret"
) // set client id and secret
   .callDiscoveryAPI(Environment.SANDBOX) // call discovery API to populate urls
   .buildConfig();

//Prepare OAuth2PlatformClient
OAuth2PlatformClient client  = new OAuth2PlatformClient(oauth2Config);

//Call refresh endpoint
BearerTokenResponse bearerTokenResponse = client.refreshToken("refreshToken"); //set refresh token

Next, retrieve the refresh token using getRefreshToken() as follows:

1
bearerTokenResponse.getRefreshToken()
Revoking a token

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
//Prepare config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder(
   "OAuth2AppClientId",
   "OAuth2AppClientSecret"
) // set client id and secret
   .callDiscoveryAPI(Environment.SANDBOX) // call discovery API to populate urls
   .buildConfig();

//Prepare OAuth2PlatformClient
OAuth2PlatformClient client  = new OAuth2PlatformClient(oauth2Config);

//Call revoke endpoint
PlatformResponse response  = client.revokeToken("refreshToken"); //set refresh token
Getting user information

To get user information, use getUserInfo(), 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
 4
 5
 6
 7
 8
 9
10
11
12
13
//Prepare config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder(
   "OAuth2AppClientId",
   "OAuth2AppClientSecret"
) // set client id and secret
   .callDiscoveryAPI(Environment.SANDBOX) // call discovery API to populate urls
   .buildConfig();

//Prepare OAuth2PlatformClient
OAuth2PlatformClient client  = new OAuth2PlatformClient(oauth2Config);

//Get user info (Use access token from bearerTokenResponse)
UserInfoResponse response = client.getUserInfo(accessToken);