intuit-oauth

library1.2.7pypypi✓ verified 26d ago

The `intuit-oauth` library is the official Python client for working with Intuit APIs, providing OAuth 2.0 and OpenID Connect implementation. It simplifies authorization, token management, and API calls for services like QuickBooks Accounting, Payments, and UserInfo. The current version is 1.2.6, with active development and regular releases addressing new features, bug fixes, and security updates.

auth-security crm-productivity payments http-networking

pip install intuit-oauth

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · INTUIT-OAUTH

intuit-oauth

auth-securitypythonv1.2.7

Install

3.2s avg

Import

427ms

Disk

39MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.452s · 40.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.2s · import 0.402s · 41MB

39MB installed

● package 39MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AuthClient

✓ from intuitlib.client import AuthClient

Scopes

✓ from intuitlib.enums import Scopes

This quickstart demonstrates how to instantiate the `AuthClient` and generate an authorization URL for the user to grant permissions. It highlights the use of `Scopes` and the necessary credentials. In a complete application, the authorization code obtained from the redirect would then be used to fetch bearer and refresh tokens.

import os from intuitlib.client import AuthClient from intuitlib.enums import Scopes # Replace with your actual credentials from Intuit Developer Portal client_id = os.environ.get('INTUIT_CLIENT_ID', 'YOUR_CLIENT_ID') client_secret = os.environ.get('INTUIT_CLIENT_SECRET', 'YOUR_CLIENT_SECRET') redirect_uri = os.environ.get('INTUIT_REDIRECT_URI', 'https://example.com/callback') environment = os.environ.get('INTUIT_ENVIRONMENT', 'sandbox') # 'sandbox' or 'production' auth_client = AuthClient( client_id, client_secret, redirect_uri, environment ) # Generate authorization URL # Scopes determine the level of access requested scopes = [Scopes.Accounting, Scopes.OpenId, Scopes.Profile, Scopes.Email] authorization_url = auth_client.get_authorization_url(scopes) print(f"Please visit this URL to authorize your app: {authorization_url}") # In a real application, you would redirect the user to this URL. # After authorization, Intuit redirects to your `redirect_uri` with `state`, `code`, and `realmId`. # You would then exchange the authorization code for tokens. # For example, after getting `auth_code` and `realm_id` from the callback URL: # try: # auth_client.get_bearer_token(auth_code, realm_id=realm_id) # print(f"Access Token: {auth_client.access_token}") # print(f"Refresh Token: {auth_client.refresh_token}") # except Exception as e: # print(f"Error getting tokens: {e}")

Debug

Known issues

breakingVersion 1.2.6 replaced the `python-jose` dependency with `pyjwt` to address CVE-2024-23342. While this is primarily an internal change, direct reliance on `python-jose` features through the library might be affected. [from release notes]

fix

Upgrade to version 1.2.6 or later.

affects: <1.2.6

gotchaPython 3.12 support was explicitly added in version 1.2.5. Users running Python 3.12 with older versions of `intuit-oauth` may encounter compatibility issues. [from release notes]

fix

Ensure you are using `intuit-oauth` version 1.2.5 or higher for Python 3.12 environments.

affects: <1.2.5

gotchaOAuth 2.0 access tokens are valid for 1 hour (3600 seconds) and refresh tokens change with every refresh and are valid for 100 days of continuous use. It is critical to store and use the latest `refresh_token` value from each server response. Failure to do so will result in `invalid_grant` errors and require user re-authorization.

fix

Always persist the latest `access_token` and `refresh_token` received after any token exchange or refresh operation.

affects: All versions

gotchaRedirect URIs used for production applications must be secured with HTTPS. HTTP redirect URIs are generally only permitted for local development (e.g., `http://localhost:port`) when using sandbox credentials.

fix

Configure your production `redirect_uri` to use HTTPS in both your Intuit Developer app settings and your application code.

affects: All versions

gotchaIntuit uses separate Client ID and Client Secret credentials for 'development' (sandbox) and 'production' environments. Using the wrong set of credentials for your target environment is a common mistake and will lead to authorization failures.

fix

Always verify that you are using the correct Client ID and Client Secret for your intended environment (sandbox or production).

affects: All versions

Errors

Common errors & fixes

{"error": "invalid_grant", "error_description": "Token has been expired or revoked."}

The authorization code is expired or has been used, or the refresh token is expired, revoked, or a new rotated refresh token was not persisted by the application. Intuit often rotates refresh tokens, making old ones invalid.

fix

Ensure you are always storing and using the *latest* refresh_token returned by the token endpoint after each successful refresh operation. If exchanging an authorization code, ensure it is used only once and before it expires. If the user has explicitly disconnected the app, they must reauthorize.

401 Unauthorized (or error code 003100/003200 'ApplicationAuthenticationFailed')

The access token used for an API call has expired (access tokens are typically valid for 1 hour), the user has revoked access to your application, or there is an issue with the realm_id or requested scopes.

fix

Implement robust logic to refresh the access token using the stored refresh token when a 401 error is encountered. If token refreshing also fails (e.g., with 'invalid_grant'), the user needs to re-authorize your application. Verify that the correct realm_id is used and that your app's scopes are properly configured and granted.

{"error":"invalid_client"}

Client authentication failed, typically due to an incorrect client_id or client_secret in your application's configuration, or because they are not being passed correctly (e.g., missing the 'Authorization: Basic' header, or incorrect base64 encoding).

fix

Verify your client_id and client_secret against your Intuit Developer account. Ensure they are correctly base64 encoded as 'client_id:client_secret' and included in the 'Authorization: Basic' header of your token exchange requests, or passed as form parameters if your client implementation requires it.

The redirect_uri query parameter value is invalid. Make sure it is listed in the Redirect URIs section on your app's keys tab and matches it exactly.

The redirect_uri provided in your authorization request does not precisely match one of the Redirect URIs configured in your application settings on the Intuit Developer portal.

fix

Navigate to your app's 'Keys & OAuth' tab in the Intuit Developer portal and ensure the redirect_uri in your code precisely matches one of the URIs listed there, including the scheme (http/https), host, port (if applicable), and path. Any mismatch, however minor, will cause this error.

ModuleNotFoundError: No module named 'intuitlib'

The 'intuit-oauth' Python package, which contains the 'intuitlib' module, is not installed in the Python environment currently being used to run your code, or there is a mismatch between the environment where it was installed and where the code is executed.

fix

Install the library using `pip install intuit-oauth`. If already installed, ensure you are running your script with the correct Python interpreter (e.g., activate your virtual environment if you are using one, or explicitly use `python3 -m pip install intuit-oauth` and `python3 your_script.py`).

Upgrade

Version history

1.2.7latest on PyPI · released Jul 22, 2026

Audit

Dependencies

pyjwtrequiredReplaced 'python-jose' for better maintenance and security in v1.2.6. [from release notes]

Agent activity

57 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/intuit/oauth-pythonclient ↗

packagehttps://pypi.org/project/intuit-oauth/ ↗

homepagehttps://developer.intuit.com ↗