Intuit’s OAuth2 and OpenID Client

View on GitHub

This client library is meant to work with Intuit’s OAuth and OpenID implementation. The bearer_token response can be used for User Info API, Accounting API and Payments API. It supports:

  • Generating Authorization URL
  • Getting OAuth2 Bearer Token
  • Getting User Info
  • Validating OpenID token
  • Refreshing OAuth2 Token
  • Revoking OAuth2 Token
  • Migrating tokens from OAuth1.0 to OAuth2

Install Client

This library can be installed using pip:

$ pip install intuit-oauth

View it on GitHub here

Docs

User Guide

Authorize your app

Step 1: Instantiate AuthClient object
auth_client = AuthClient(
    client_id,
    client_secret,
    redirect_uri,
    environment,
)

Valid values for environment include sandbox and production. redirect_uri should be set in your Intuit Developer app’s Keys tab under the right environment.

Step 2: Get Authorization URL

Get authorization url by specifying list of intuitlib.enums.Scopes

url = auth_client.get_authorization_url([Scopes.Accounting])

After user connects to the app, the callback URL has params for state, auth_code and realm_id (realm_id for Accounting and Payments scopes only)

Step 3: Get Tokens and Expiry details

The auth_code from URL params from Step 2 is used to get bearer tokens. Optionally, realm_id is passed to set this property for auth_client object.

auth_client.get_bearer_token(auth_code, realm_id=realm_id)

After successful response, access_token, refresh_token, etc properties of auth_client object are set.

Step 4 (OAuth): Sample API Call

Here’s a sample API call to show how to use access_token to get CompanyInfo for Accounting API.

base_url = 'https://sandbox-quickbooks.api.intuit.com'
url = '{0}/v3/company/{1}/companyinfo/{1}'.format(base_url, auth_client.realm_id)
auth_header = 'Bearer {0}'.format(auth_client.access_token)
headers = {
    'Authorization': auth_header,
    'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
Step 4 (OpenID): User Info API call

User Info is returned by this method for OpenID scope only:

response = auth_client.get_user_info()

Or by passing the access_token as a parameter:

response = auth_client.get_user_info(access_token='EnterAccessTokenHere')

Refresh Tokens

Validity for Intuit’s access_token is 60 min and refresh_token is 24 hours. A fresh access_token and refresh_token can be retrieved by calling the refresh token endpoint. If auth_client.refresh_token property is already set, this can be done by:

auth_client.refresh()

Or by passing the refresh_token as a parameter:

auth_client.refresh(refresh_token='EnterRefreshTokenHere')

Revoke Tokens

If auth_client.refresh_token or auth_client.access_token property is already set, this can be done by:

auth_client.revoke()

Alternatively, pass the refresh_token or access_token as a parameter:

auth_client.revoke(token='EnterAccessOrRefreshTokenHere')

If successfully revoked, this method returns True

Migrate OAuth 1.0a Tokens

Migration module migrates OAuth 1.0a token to OAuth2 tokens. The method takes in valid OAuth 1.0a tokens (consumer_key, consumer_secret, access_key, access_secret), auth_client object from intuitlib.client.AuthClient object as well as list of intuitlib.enum.Scopes

migrate(
    consumer_key,
    consumer_secret,
    access_key,
    access_secret,
    auth_client,
    [Scopes.ACCOUNTING]
)

Error Handling

In case of HTTP Errors, the client raises intuitlib.exceptions.AuthClientError which has properties status_code, intuit_tid, timestamp, etc which can used for troubleshooting or while contacting Support

try:
    auth_client.get_bearer_token(auth_code, realm_id=realm_id)
except AuthClientError as e:
    # just printing here but it can be used for retry workflows, logging, etc
    print(e.status_code)
    print(e.content)
    print(e.intuit_tid)

Reference

AuthClient

class intuitlib.client.AuthClient(client_id, client_secret, redirect_uri, environment, state_token=None, access_token=None, refresh_token=None, id_token=None, realm_id=None)

Bases: requests.sessions.Session

Handles OAuth 2.0 and OpenID Connect flows to get access to User Info API, Accoutning APIs and Payments APIs

get_authorization_url(scopes, state_token=None)

Generates authorization url using scopes specified where user is redirected to

Parameters:
  • scopes (list of enum, intuitlib.enums.Scopes) – Scopes for OAuth/OpenId flow
  • state_token – CSRF token, defaults to None
Returns:

Authorization url
get_bearer_token(auth_code, realm_id=None)

Gets access_token and refresh_token using authorization code

Parameters:
  • auth_code – Authorization code received from redirect_uri
  • realm_id – Realm ID/Company ID of the QBO company
Raises:

intuitlib.exceptions.AuthClientError – if response status != 200
get_user_info(access_token=None)

Gets User Info based on OpenID scopes specified

Parameters:

access_token – Access token
Raises:
Returns:

Requests object
refresh(refresh_token=None)

Gets fresh access_token and refresh_token

Parameters:

refresh_token – Refresh Token
Raises:
revoke(token=None)

Revokes access to QBO company/User Info using either valid Refresh Token or Access Token

Parameters:

token – Refresh Token or Access Token to revoke
Raises:
Returns:

True if token successfully revoked

OAuth Migration

This module helps in migrating OAuth 1.0a tokens to OAuth 2.0

intuitlib.migration.migrate(consumer_key, consumer_secret, access_token, access_secret, auth_client, scopes)

Migrates OAuth1 tokens to OAuth2 tokens

Parameters:
  • consumer_key – OAuth1 Consumer Key
  • consumer_secret – OAuth1 Consumer Secret
  • access_token – OAuth1 Access Token
  • access_secret – OAuth1 Access Secret
  • auth_client (intuitlib.client.AuthClient) – AuthClient for OAuth2 specs
  • scopes – list of intuitlib.enum.Scopes
Raises:

AuthClientError – if response status != 200

Scopes Enum

class intuitlib.enums.Scopes

Bases: enum.Enum

Scopes supported by Intuit for OAuth and OpenID flows

ACCOUNTING = 'com.intuit.quickbooks.accounting'
ADDRESS = 'address'
EMAIL = 'email'
OPENID = 'openid'
PAYMENT = 'com.intuit.quickbooks.payment'
PHONE = 'phone'
PROFILE = 'profile'

Exceptions

class intuitlib.exceptions.AuthClientError(response)

Bases: exceptions.Exception

AuthClient Error object in case API response status != 200

Helper Module

This module contains utility methods used by this library

intuitlib.utils.generate_token(length=30, allowed_chars='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')

Generates random CSRF token

Parameters:
  • length – Length of CSRF token, defaults to 30
  • allowed_chars – Characters to use, defaults to ‘abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789’
Returns:

Token string
intuitlib.utils.get_auth_header(client_id, client_secret)

Gets authorization header

Parameters:
  • client_id – Client ID
  • client_secret – Client Secret
Returns:

Authorization header
intuitlib.utils.get_discovery_doc(environment, session=None)

Gets discovery doc based on environment specified.

Parameters:
  • environment – App environment, accepted values: ‘sandbox’,’production’,’prod’,’e2e’
  • session – requests.Session object if a session is already being used, defaults to None
Returns:

Discovery doc response
Raises:

HTTPError – if response status != 200
intuitlib.utils.get_jwk(kid, jwk_uri)

Get JWK for public key information

Parameters:
  • kid – KID
  • jwk_uri – JWK URI
Raises:

HTTPError – if response status != 200
Returns:

dict containing keys
intuitlib.utils.scopes_to_string(scopes)

Converts list of enum to string

Parameters:scopes (list of intuitlib.enums.Scopes) – Scopes specified for OAuth/OpenID flow
Raises:TypeError – for invalid input for scope
Returns:Scopes string
intuitlib.utils.send_request(method, url, header, obj, body=None, session=None, oauth1_header=None)

Makes API request using requests library, raises intuitlib.exceptions.AuthClientError if request not successful and sets specified object attributes from API response if request successful

Parameters:
  • method – HTTP method type
  • url – request URL
  • header – request headers
  • obj – object to set the attributes to
  • body – request body, defaults to None
  • session – requests session, defaults to None
  • oauth1_header – OAuth1 auth header, defaults to None
Raises:

AuthClientError – In case response != 200
Returns:

requests object
intuitlib.utils.set_attributes(obj, response_json)

Sets attribute to an object from a dict

Parameters:
  • obj – Object to set the attributes to
  • response_json – dict with key names same as object attributes
intuitlib.utils.validate_id_token(id_token, client_id, intuit_issuer, jwk_uri)

Validates ID Token returned by Intuit

Parameters:
  • id_token – ID Token
  • client_id – Client ID
  • intuit_issuer – Intuit Issuer
  • jwk_uri – JWK URI
Returns:

True/False

Note

The API endpoints in this library only work with TLS 1.2

License

This library is provided under Apache 2.0 which is found here

Indices and tables