OAuth 2.0

The QuickBooks Payments APIs uses the OAuth 2.0 protocol for authentication and authorization. Intuit supports use cases for server and client applications.

To begin, obtain OAuth 2.0 client credentials by creating a new QuickBooks Payments application in your Intuit Developer Account. Then your application requests an access token from the Intuit’s Authorization Server, extracts a token from the response, and sends the token to the QuickBooks API that you want to access. For an interactive demonstration of using OAuth 2.0 with QuickBooks Online or Payments (including the option to use your own client credentials), experiment with the OAuth 2.0 Playground.

This page gives an overview of the OAuth 2.0 authorization scenarios that QuickBooks supports. For details about using OAuth 2.0 for authentication, see OpenID Connect

Obtain OAuth 2.0 credentials such as a client id and client secret from the “keys” tab after creating a QuickBooks Payments application in developer.intuit.com/myapps.

Define redirect URIs: Under the keys, you can define one or more redirect URIs. These URIs handle responses from the OAuth 2.0 server and are called after the user authorizes the connection. URIs in this list are the only ones to which the authorization response can be sent from the OAuth 2.0 server.

You must define at least one URI specifically for your application’s auth endpoint before you can use OAuth 2.0. For the sandbox environment, this list can include localhost. As a best practice, design your app’s auth endpoints in a way that doesn’t expose authorization codes to other resources on the page.

Before your application can access data using QuickBooks Payments API, it must obtain an access token that grants access to the API. A single access token can grant varying degrees of access to multiple APIs. Scope parameter used while requesting the access token controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

Obtaining the token requires an authentication step where the user logs in with their merchant account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.

If the user grants the permission, the Intuit Authorization Server sends your application an authorization code at the callback endpoint that you defined in the Redirect URL section of the Keys tab of your app. This authorization code can be exchanged to obtain the access token. If the user does not grant the permission, the server returns an error.

It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front.

View Screenshot

Your first step is to create the authorization request with the parameters that identify your application and permissions that the user will be asked to grant to your application.

If you use one of our client library for OAuth 2.0, you create and configure an object that defines these parameters. If you call the Intuit OAuth 2.0 endpoint directly, you’ll generate a URL and set the parameters on that URL.

1
2
3
4
5
6
7
8
9

// Instantiate object
public static OAuth2Client oauthClient = new OAuth2Client(“clientid”, “clientsecret”, “redirectUrl”, “environment”); // environment is “sandbox” or “production”

//Prepare scopes
List<OidcScopes> scopes = new List<OidcScopes>();
scopes.Add(OidcScopes.Payment);

//Get the authorization URL
string authorizeUrl = oauthClient.GetAuthorizationURL(scopes);

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

//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder("clientId", "clientSecret")
        .callDiscoveryAPI(Environment.SANDBOX).buildConfig();

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$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.payment",
      'baseUrl' => "Development/Production"
));
$OAuth2LoginHelper = $dataService->getOAuth2LoginHelper();
$authorizationCodeUrl = $OAuth2LoginHelper->getAuthorizationCodeURL();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Instance of client
var oauthClient = new OAuthClient({
    clientId: '<Enter your clientId>',
    clientSecret: '<Enter your clientSecret>',
    environment: 'sandbox',                                // ‘sandbox’ or ‘production’
    redirectUri: '<Enter your redirectUri>'
});

// AuthorizationUri
var authUri = oauthClient.authorizeUri({scope:[OAuthClient.scopes.Payment,OAuthClient.scopes.OpenId],state:'testState'});  // can be an array of multiple scopes ex : {scope:[OAuthClient.scopes.Payment,OAuthClient.scopes.OpenId]}

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

from intuitlib.client import AuthClient
from intuitlib.enums import Scopes

//Instantiate client
auth_client = AuthClient(
    “client_id”,
    “client_secret”,
    “redirect_uri”,
    “Environment”, # “sandbox” or “production”
)

// Prepare scopes
scopes = [
    Scopes.PAYMENT,
]

// Get authorization URL
auth_url = auth_client.get_authorization_url(scopes)

1
2
3
4
5
6
7
8
9

require 'intuit-oauth'

client = IntuitOAuth::Client.new('client_id', 'client_secret', 'redirectUrl', 'environment')
scopes = [
    IntuitOAuth::Scopes::PAYMENT
]

authorizationCodeUrl = oauth_client.code.get_auth_uri(scopes)
# => https://appcenter.intuit.com/connect/oauth2?client_id=clientId&redirect_uri=redirectUrl&response_type=code&scope=com.intuit.quickbooks.payment&state=rMwcoDITc2N6FJsUGGO9

Retrieve the base URI from the Discovery Document using the key, authorization_endpoint. The discussion here assumes the base URI is https://appcenter.intuit.com/connect/oauth2 that includes the following parameters:

Redirect the user to Intuit’s OAuth 2.0 server using the URL prepared above to initiate the authentication and authorization process. This step is required when your application first needs to access user’s data. In the case of incremental authorization, this step also occurs when your application first needs to access additional resources that it does not yet have permission to access.

1
2

// Redirect the authorization URL
return Redirect(authorizeUrl);

1
2

//Use standard url redirect-
resp.sendRedirect(url);

1
2

//redirect users to authorization screen url
header('Location: '. $authorizationCodeUrl);

1
2

// Redirect the authUri
res.redirect(authUri);

1
2

//Using standard redirect
return redirect(auth_url)

1

redirect_to(authorizationCodeUrl);

Here is an example of a complete authorization request URI specifying the com.intuit.quickbooks.payment scope, with line breaks and spaces for readability

1
2

POST https://appcenter.intuit.com/connect/oauth2?
client_id=Q3ylJatCvnkYqVKLmkH1zWlNzNWB5CkYB36b5mws7HkKUEv9aI&response_type=code&scope=com.intuit.quickbooks.payment&redirect_uri=https://www.mydemoapp.com/oauth-redirect&state=security_token%3D138r5719ru3e1%26url%3Dhttps://www.mydemoapp.com/oauth-redirect&

The following snippet shows complete authorization request URI using cURL:

1

curl -X POST '< Authorization URI from Step 1>'

In this step, the user decides whether to grant your application the requested access. At this stage, Intuit displays a consent window to the user showing the name of your application and the QuickBooks Online Company (with payments enabled) or merchant account that it is requesting permission to access with the user’s authorization credentials. The user can then consent or refuse to grant access to your application.

Your application doesn’t need to do anything at this stage as it waits for the response from Intuit’s OAuth 2.0 server indicating whether the access was granted.

The OAuth 2.0 server responds to your application’s access request by using the redirect_uri specified in the request.

If the user approves the access request, then the response contains an authorization code. An example callback looks like this:

1
2

https://www.mydemoapp.com/oauth-redirect?state=security_token%3D138r5719ru3e1%26url
%3Dhttps://www.mydemoapp.com/oauth-redirect&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&realmId=1231434565226279

If the user does not approve the request, the response contains an error message as shown below:

After the app receives the authorization code, it should exchange the authorization code for refresh and access tokens

1
2

oauth2Token = oauth_client.token.get_bearer_token('the authorization code returned from authorizationCodeUrl')
# => #<IntuitOAuth::ClientResponse:0x00007f9152b5c418 @access_token="the access token", @expires_in=3600, @refresh_token="the refresh token", @x_refresh_token_expires_in=8726400>

Retrieve the base URI from the Discovery Document using the key, token_endpoint. The discussion here assumes the base URI (https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer) sends an HTTPS POST request to the URL above that includes the following parameters:

The following snippet shows a sample request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer HTTP/1.1
Accept: application/json
Authorization: Basic UTM0dVBvRDIwanp2OUdxNXE1dmlMemppcTlwM1d2
    NzRUdDNReGkwZVNTTDhFRWwxb0g6VEh0WEJlR3dheEtZSlVNaFhzeGxma1l
    XaFg3ZlFlRzFtN2szTFRwbw==
Content-Type: application/x-www-form-urlencoded
Host: oauth.platform.intuit.com
Body: grant_type=authorization_code&
code=L3114709614564VSU8JSEiPkXx1xhV8D9mv4xbv6sZJycibMUI&
redirect_uri=https://www.mydemoapp.com/oauth-redirect

The following snippet shows a sample request using cURL:

1
2
3
4
5
6
7

curl -X POST 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: REPLACE_WITH_AUTHORIZATION_HEADER (details below)' \
-d 'grant_type=authorization_code' \
-d 'code=REPLACE_WITH_AUTHORIZATION_CODE' \
-d 'redirect_uri=REPLACE_WITH_REDIRECT_URI'

The Authorization header is in the format - Authorization: Basic <credentials>, where credentials is the Base64 encoding of client id and client secret joined by a single colon ‘:’ as shown below -

1

"Basic " + base64encode(client_id + ":" + client_secret)

The token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

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

{
"token_type": "bearer",
"expires_in": 3600,
"refresh_token":"Q311488394272qbajGfLBwGmVsbF6VoNpUKaIO5oL49aXLVJUB",
"x_refresh_token_expires_in":15551893,
"access_token":"eJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGGlyIn0..KM1_Fezsm6BUSaqqfTedaA.
dBUCZWiVmjH8CdpXeh_pmaM3kJlJkLEqJlfmavwGQDThcf94fbj9nBZkjEPLvBcQznJnEmltCIvsTGX0ue_w45h7_
yn1zBoOb-1QIYVE0E5TI9z4tMUgQNeUkD1w-X8ECVraeOEecKaqSW32Oae0yfKhDFbwQZnptbPzIDaqiduiM_q
EFcbAzT-7-znVd09lE3BTpdMF9MYqWdI5wPqbP8okMI0l8aa-UVFDH9wtli80zhHb7GgI1eudqRQc0sS9zWWb
I-eRcIhjcIndNUowSFCrVcYG6_kIj3uRUmIV-KjJUeXdSV9kcTAWL9UGYoMnTPQemStBd2thevPUuvKrPdz3ED
ft-RVRLQYUJSJ1oA2Q213Uv4kFQJgNinYuG9co_qAE6A2YzVn6A8jCap6qGR6vWHFoLjM2TutVd6eOeYoL2bb7jl
QALEpYGj4E1h3y2xZITWvnmI0CEL_dYQX6B3QTO36TDaVl9WnTaCCgAcP6bt70rFlPYbCjOxLoI6qFm5pUwGLLp
67JZ36grc58k7NIyKJ8dLJUL_Q9r1WoUvw.ZS298t_u7dSlkfajxLfO9Q"
}

Access tokens are valid for 60 minutes (one hour), after which you need to get a new one using the latest refresh_token returned to you from the previous request. You must write your code to anticipate the possibility that a granted access token might no longer work.

Access tokens periodically expire. You can refresh an access token without prompting the user for permission.

1
2
3
4
5

// Instantiate object
public static OAuth2Client oauthClient = new OAuth2Client(“clientid”, “clientsecret”, “redirectUrl”, “environment”); // environment is “sandbox” or “production”

//Refresh token endpoint
var tokenResp = await oauthClient.RefreshTokenAsync(“refreshToken”);

1
2
3
4
5
6
7
8

//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder("OAuth2AppClientId", "OAuth2AppClientSecret").callDiscoveryAPI(Environment.SANDBOX).buildConfig();

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

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

1
2
3
4
5

$oauth2LoginHelper = new OAuth2LoginHelper($ClientID,$ClientSecret);
$accessTokenObj = $oauth2LoginHelper->
                    refreshAccessTokenWithRefreshToken($theRefreshTokenValue);
$accessTokenValue = $accessTokenObj->getAccessToken();
$refreshTokenValue = $accessTokenObj->getRefreshToken();

1
2
3
4
5
6
7
8

   oauthClient.refresh()
        .then(function(authResponse) {
            console.log('Tokens refreshed : ' + JSON.stringify(authResponse.json()));
        })
        .catch(function(e) {
            console.error("The error message is :"+e.originalMessage);
            console.error(e.intuit_tid);
        });

1
2
3
4
5
6
7
8
9

//Instantiate client
auth_client = AuthClient(
    “client_id”,
    “client_secret”,
    “redirect_uri”,
    “Environment”, # “sandbox” or “production”
)
// Refresh token endpoint
auth_client.refresh(refresh_token=”refresh_token”)

1

To refresh an access token, your application sends an HTTPS POST request to Intuit’s authorization server (https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer) that includes the following parameters:

The following snippet shows a sample request:

1
2
3
4
5
6
7
8

POST /oauth2/v1/tokens/bearer HTTP/1.1
Accept: application/json
Authorization: Basic UTM0dVBvRDIwanp2OUdxNXE1dmlMemppcTlwM1d2
    NzRUdDNReGkwZVNTTDhFRWwxb0g6VEh0WEJlR3dheEtZSlVNaFhzeGxma1l
    XaFg3ZlFlRzFtN2szTFRwbw==
Content-Type: application/x-www-form-urlencoded
Body: grant_type=refresh_token&
refresh_token=Q311488394272qbajGfLBwGmVsbF6VoNpUKaIO5oL49aXLVJUB

The following snippet shows a sample request using cURL:

1
2
3
4
5
6

curl -X POST 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: REPLACE_WITH_AUTHORIZATION_HEADER (details below)'  \
-d 'grant_type=refresh_token' \
-d 'refresh_token=REPLACE_WITH_REFRESH_TOKEN'

The Authorization header is in the format - Authorization: Basic <credentials>, where credentials is the Base64 encoding of client id and client secret joined by a single colon ‘:’ as shown below -

1

"Basic " + base64encode(client_id + ":" + client_secret)

As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

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

{
"token_type": "bearer",
"expires_in": 3600,
"refresh_token":"Q311488394272qbajGfLBwGmVsbF6VoNpUKaIO5oL49aXLVJUB",
"x_refresh_token_expires_in":15551893,
"access_token":"eJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGGlyIn0..KM1_Fezsm6BUSaqqfTedaA.
dBUCZWiVmjH8CdpXeh_pmaM3kJlJkLEqJlfmavwGQDThcf94fbj9nBZkjEPLvBcQznJnEmltCIvsTGX0ue_w45h7_
yn1zBoOb-1QIYVE0E5TI9z4tMUgQNeUkD1w-X8ECVraeOEecKaqSW32Oae0yfKhDFbwQZnptbPzIDaqiduiM_q
EFcbAzT-7-znVd09lE3BTpdMF9MYqWdI5wPqbP8okMI0l8aa-UVFDH9wtli80zhHb7GgI1eudqRQc0sS9zWWb
I-eRcIhjcIndNUowSFCrVcYG6_kIj3uRUmIV-KjJUeXdSV9kcTAWL9UGYoMnTPQemStBd2thevPUuvKrPdz3ED
ft-RVRLQYUJSJ1oA2Q213Uv4kFQJgNinYuG9co_qAE6A2YzVn6A8jCap6qGR6vWHFoLjM2TutVd6eOeYoL2bb7jl
QALEpYGj4E1h3y2xZITWvnmI0CEL_dYQX6B3QTO36TDaVl9WnTaCCgAcP6bt70rFlPYbCjOxLoI6qFm5pUwGLLp
67JZ36grc58k7NIyKJ8dLJUL_Q9r1WoUvw.ZS298t_u7dSlkfajxLfO9Q"
}

Your app can programmatically revoke access given to it by a specific user when they click the Disconnect link in your app. Use the revoke endpoint to request permissions granted to the application to be removed.

1
2
3
4
5

// Instantiate object
public static OAuth2Client oauthClient = new OAuth2Client(“clientid”, “clientsecret”, “redirectUrl”, “environment”); // environment is “sandbox” or “production”

//Revoke token endpoint
var tokenResp = await oauthClient.RevokeTokenAsync(“refreshToken");

1
2
3
4
5
6
7
8

//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder("OAuth2AppClientId", "OAuth2AppClientSecret").callDiscoveryAPI(Environment.SANDBOX).buildConfig();

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

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

1
2

$oauth2LoginHelper = new OAuth2LoginHelper($clientID,$clientSecret);
$revokeResult = $oauth2LoginHelper->revokeToken($yourToken);

1
2
3
4
5
6
7
8

oauthClient.revoke(params)
        .then(function(authResponse) {
            console.log('Tokens revoked : ' + JSON.stringify(authResponse.json()));
        })
        .catch(function(e) {
            console.error("The error message is :"+e.originalMessage);
            console.error(e.intuit_tid);
        });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

//Instantiate client
auth_client = AuthClient(
    “client_id”,
    “client_secret”,
    “redirect_uri”,
    “Environment”, # “sandbox” or “production”
)

// Refresh token endpoint
auth_client.revoke(token=”refresh_token”)

1

trueOrFalse = oauth_client.token.revoke_tokens('the_token_you_want_to_revoke')

1
2

$ ls -lsa .
$ make file

To revoke an token, your application sends an HTTPS POST request to revoke endpoint (https://developer.api.intuit.com/v2/oauth2/tokens/revoke) and includes the token as a parameter

The following snippet shows a sample request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST https://developer.api.intuit.com/v2/oauth2/tokens/revoke HTTP/1.1
Accept: application/json
Authorization: Basic UTM0dVBvRDIwanp2OUdxNXE1dmlMemppcTlwM1d2
    NzRUdDNReGkwZVNTTDhFRWwxb0g6VEh0WEJlR3dheEtZSlVNaFhzeGxma1l
    XaFg3ZlFlRzFtN2szTFRwbw==
Content-Type: application/json

{
    "token": "{bearerToken or refreshToken}"
}

The following snippet shows a sample request using cURL:

1
2
3
4
5

curl -X POST 'https://developer.api.intuit.com/v2/oauth2/tokens/revoke' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: REPLACE_WITH_AUTHORIZATION_HEADER (details below)' \
-d 'token:REPLACE_WITH_REFRESH_TOKEN/REPLACE_WITH_ACCESS_TOKEN'

The Authorization header is in the format - Authorization: Basic <credentials>, where credentials is the Base64 encoding of client id and client secret joined by a single colon ‘:’ as shown below -

1

"Basic " + base64encode(client_id + ":" + client_secret)

If the revocation is successfully processed, then the status code of the response is 200. For error conditions, a status code 400 is returned along with an error code.

The OAuth 2.0 playground is a tool to walk through each step of both the OAuth 2.0 and OpenID Connect workflows. The playground demonstrates the following steps:

Invoke the OAuth 2.0 playground directly, or from your app’s dashboard. Authorize the connection between your app and the QuickBooks Online Company (with payments enabled), sandbox company or merchant account.

After your application obtains an access token, you can use it to make calls to QuickBooks Payments API resources. To do this, include the access token in a request to the API by including it in the Authorization: Bearer HTTP header. You can try out all the QuickBooks Payments APIs and view their scopes at the OAuth 2.0 Playground.

Example

A call to the production charges endpoint to read a given charges object using the access_token parameter might look like the following, though you’ll need to specify your own access token:

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

GET https://api.intuit.com/quickbooks/v4/payments/charges/<id> ​​​
Authorization=Bearer eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..eF2J3XEDnGBjpO469rw9Dw.Gi3Oc
   UsfFm8Pnxw1aneLN-5o0j_nE0G9t6jbvAFgMy4-QYkmzUCVmgJWCj9HTZ2ojgQaKjYoEwZMO3uBvs
   QUo8UIdZIOQz_3HxXggq9VIlhihH7d1NXLiFMC8dQGtFhECGypv6xJ8Ob7Ay00CbEq_tns1wgfXXFgr
   L-FcoWtuubxHUjKE7EwlM8nB0VQG1VTwjWzEcPPTr7EjK0KQWa9vXzs6W24s09mXZMli0axYobcuB
   GuFwt4RCfxARGOdyu8J9tg-QziFPX3TwIVMsAxKLdDZkMcy1fEyXW_A0H3z6IcKzvjxFRl10cASRmNb
   wSGHk8C1W89HLbeeL_wx_Bg6qTpMBjBqnpGYMVG9vSy-fmKDPd6Uysw3DvvOYkX5pFGkln6X5F2fcdxw
   VaV05IGUyxsX-Je4UY671P54ScRVlEXTAQpnmhCiR4euadvPmKqNtk70n02ExAkMJ5UbyS2mcupPjXk7C67
   qVu2kfVMLFFdg1AKhBzlpl-KqvTsgO2-bHYpKS9qwLP1CdKw_1NxB9cvjBmGQ3S33P6WjEg_eNM.rZ1h6
   s-rQb2D_PX8dIYb5g
Accept=*/*
Content-Type=application/json;charset=UTF-8

The Refresh Access Token panel is populated with the current access and refresh tokens. Click Refresh Access Token to refresh the token. As a general rule, access tokens need to be refreshed every 60 minutes. Click here for further information about refreshing access tokens.

• OAuth 2.0 sample integrations included in SDKs: .NET, Java, PHP
• Sample OAuth 2.0 implementations that are SDK independent: .NET, .NET MVC 5, Go, Java, Node.js, Python, Ruby