OAuth Scopes Reference

This page provides a comprehensive reference for all OAuth scopes requested by the QuickBooks Invoicing integration. Understanding these scopes helps you know exactly what data the integration can access and why each permission is necessary.

Overview

The QuickBooks Invoicing integration requests 6 OAuth scopes from HubSpot during installation. All scopes are read-only and follow the principle of least privilege.

Scope Summary Table

Detailed Scope Descriptions

1. Base OAuth (oauth)

Scope Identifier: oauth

Permission Level: Base OAuth authentication

What it allows:

• Establishes secure OAuth 2.0 authentication framework
• Enables token-based API access to HubSpot
• Manages OAuth access and refresh tokens
• Required foundation for all OAuth-based integrations

Why we need it:

• Mandatory for any OAuth 2.0 integration
• Provides secure authentication mechanism
• Enables API communication between HubSpot and the integration
• Manages token lifecycle (issuance, refresh, revocation)

Data directly accessed: None. This is the authentication framework only.

Security:

• Tokens encrypted using AES-256-GCM
• Tokens stored with derived encryption keys (PBKDF2, 100,000 iterations)
• Tokens deleted immediately upon disconnection
• No plain-text token storage

2. Contact Read (crm.objects.contacts.read)

Scope Identifier: crm.objects.contacts.read

Permission Level: Read-only access to contact records

What it allows:

• Read contact first and last names
• Access contact email addresses
• View contact phone numbers
• Read contact company associations
• Access billing address information
• View contact lifecycle stage
• Read contact owner information

Why we need it:

• Customer Sync: Sync HubSpot contacts to QuickBooks customers
• Invoice Recipients: Populate customer information on invoices
• Email Delivery: Send invoices to contact email addresses
• Billing Information: Use contact billing address for invoices
• Customer Matching: Match HubSpot contacts to existing QuickBooks customers

Specific properties accessed:

firstname, lastname, email, phone, company,
address, city, state, zip, country,
lifecyclestage, hs_object_id

What we DON’T do:

• ❌ Modify contact records
• ❌ Create new contacts
• ❌ Delete contacts
• ❌ Change contact properties
• ❌ Update contact associations
• ❌ Access contact notes or communications
• ❌ Read custom contact properties (unless explicitly used for customer sync)

Data flow:

HubSpot Contact → Integration Backend → QuickBooks Customer API

Frequency of access:

• On-demand when creating invoices
• When syncing new customers to QuickBooks
• When searching for existing customers
• No background polling or continuous access

3. Deal Read (crm.objects.deals.read)

Scope Identifier: crm.objects.deals.read

Permission Level: Read-only access to deal records

What it allows:

• Read deal names and descriptions
• Access deal amounts and currency
• View deal stage information
• Read deal pipelines
• Access deal associations (contacts, companies, quotes)
• View deal properties (close date, create date)
• Read deal owner information

Why we need it:

• Invoice Creation: Create invoices from deal data
• Amount Calculation: Use deal amounts for invoice totals
• Customer Association: Link deals to contacts for invoicing
• Quote Integration: Access deal-associated quotes
• Display in CRM Card: Show deal information in QuickBooks Invoices tab

Specific properties accessed:

dealname, amount, dealstage, pipeline, closedate,
createdate, hs_object_id, currency, deal_currency_code

What we DON’T do:

• ❌ Modify deal properties
• ❌ Change deal stages
• ❌ Update deal amounts
• ❌ Create or delete deals
• ❌ Update deal associations
• ❌ Change deal owners
• ❌ Access deal notes or activities

Data flow:

HubSpot Deal → Integration Backend → Invoice Creation Form

Frequency of access:

• When user opens QuickBooks Invoices card on a deal
• When creating invoices from a deal
• When calculating invoice amounts
• No background access when user is not interacting with the card

4. Line Items Read (crm.objects.line_items.read)

Scope Identifier: crm.objects.line_items.read

Permission Level: Read-only access to line items

What it allows:

• Read line item names and descriptions
• Access product information
• View line item prices and quantities
• Read discount information
• Access tax information on line items
• View line item associations to deals

Why we need it:

• Itemized Invoices: Create detailed invoices with line items
• Amount Calculation: Calculate total deal amounts including line items
• Product Reference: Reference products for invoice line items
• Tax Calculation: Apply appropriate tax to each line item
• Discount Application: Include discounts in invoice totals

Specific properties accessed:

name, price, quantity, amount, discount, hs_sku,
description, hs_product_id, tax

What we DON’T do:

• ❌ Modify line items
• ❌ Create or delete line items
• ❌ Change line item prices
• ❌ Update quantities
• ❌ Modify discounts
• ❌ Change product associations

Data flow:

HubSpot Line Items → Integration Backend → Invoice Line Items Calculation

Frequency of access:

• When calculating deal totals
• When creating itemized invoices
• When displaying invoice preview
• Only when user initiates invoice creation

5. Quotes Read (crm.objects.quotes.read)

Scope Identifier: crm.objects.quotes.read

Permission Level: Read-only access to quote records

What it allows:

• Read quote titles and names
• Access quote amounts and totals
• View quote status (draft, signed, etc.)
• Read quote line items
• Access quote associations to deals
• View quote expiration dates
• Read quote signature status

Why we need it:

• Signed Quote Invoicing: Only create invoices from signed quotes
• Amount Accuracy: Use quote amounts for invoice totals
• Line Item Import: Import quote line items into invoices
• Quote Validation: Verify quote is signed before invoicing
• Customer Confidence: Ensure invoice matches signed quote

Specific properties accessed:

hs_title, hs_quote_amount, hs_status, hs_expiration_date,
hs_public_url_key, hs_esign_num_signers_signed

What we DON’T do:

• ❌ Modify quotes
• ❌ Change quote status
• ❌ Update quote amounts
• ❌ Create or delete quotes
• ❌ Send quotes
• ❌ Mark quotes as signed
• ❌ Change quote expiration dates

Data flow:

HubSpot Quote → Integration Backend → Quote Status Check → Invoice Amount

Frequency of access:

• When user selects quote-based invoice creation
• When validating quote signature status
• When importing quote line items
• Only for deals with associated quotes

6. Invoices Read (crm.objects.invoices.read)

Scope Identifier: crm.objects.invoices.read

Permission Level: Read-only access to HubSpot invoice objects

What it allows:

• Read HubSpot invoice records (if you use them)
• Access invoice status in HubSpot
• View invoice associations
• Read invoice amounts and dates

Why we need it:

• Future Compatibility: Support for HubSpot’s native invoice objects
• Status Tracking: Potential invoice status synchronization
• Dual System Support: Work with both HubSpot and QuickBooks invoices
• Data Consistency: Maintain consistency across systems

Note: This integration creates invoices in QuickBooks, not HubSpot. This scope is for future compatibility and potential synchronization features.

What we DON’T do:

• ❌ Create HubSpot invoices
• ❌ Modify invoice status in HubSpot
• ❌ Delete HubSpot invoices
• ❌ Currently use this scope in active features

Current usage: Reserved for future features. Not actively used in current version.

Scope Justification Matrix

Security and Privacy

Read-Only Access

Important: All scopes are read-only. The integration cannot:

• ❌ Create, update, or delete contacts
• ❌ Create, update, or delete deals
• ❌ Modify line items or quotes
• ❌ Change any HubSpot data
• ❌ Send emails on your behalf (besides QuickBooks invoice emails)
• ❌ Access data from other HubSpot objects (companies, tickets, etc.)

Data Minimization

We only request the minimum scopes necessary for the integration to function. We do NOT request:

• ❌ Write access to any CRM objects
• ❌ Access to companies, tickets, or other objects
• ❌ Marketing email scopes
• ❌ Workflow or automation scopes
• ❌ Settings or account configuration scopes
• ❌ User management scopes

Least Privilege Principle

Each scope requested follows the principle of least privilege:

1. Only read access, never write
2. Only specific objects needed for invoicing
3. Only standard properties, not all custom properties
4. Only when user initiates actions, not continuous polling

Token Security

OAuth tokens with these scopes are protected:

• Encrypted at rest: AES-256-GCM encryption
• Derived keys: PBKDF2 with 100,000 iterations
• Account-specific: Unique encryption key per HubSpot account
• Immediately deleted: Upon disconnection or uninstall
• Never transmitted to browser: Server-side only

See Security Best Practices for technical details.

Privacy Guarantee

After you disconnect or uninstall:

• ✅ OAuth tokens permanently deleted (< 1 second)
• ✅ No API access to your HubSpot data
• ✅ No background processes accessing your data
• ✅ Complete data privacy restored

We cannot access your HubSpot data without active OAuth tokens.

Scope Approval

During Installation

When you install the integration, HubSpot will show a consent screen with:

1. App name: QuickBooks Invoicing
2. List of scopes: All 6 scopes listed above
3. Description: What each scope allows
4. Connect app button: To approve scopes

All scopes required: You must approve all scopes for the integration to function. Partial approval is not supported.

Reviewing Approved Scopes

To see what scopes you’ve approved:

1. Go to Settings → Integrations → Connected Apps
2. Click on QuickBooks Invoicing
3. View the Scopes or Permissions section
4. All approved scopes will be listed

Revoking Scopes

To revoke scopes:

1. Go to Settings → Integrations → Connected Apps
2. Find QuickBooks Invoicing
3. Click Uninstall or Revoke Access
4. All scopes are revoked simultaneously

You cannot revoke individual scopes without uninstalling the app.

Comparison with Other Integrations

QuickBooks Desktop Apps

Some QuickBooks Desktop integrations may request:

• Write access to contacts, deals
• Access to companies and tickets
• Marketing and sales automation scopes

Our integration: Read-only access to only necessary objects.

Native HubSpot Invoicing

If you use HubSpot’s native invoicing features, those may require:

• crm.objects.invoices.write - Create invoices in HubSpot
• Payment processing scopes
• Commerce scopes

Our integration: Creates invoices in QuickBooks, not HubSpot. Read-only access to HubSpot invoices for future compatibility only.

Frequently Asked Questions

Why do you need contact access?

To sync HubSpot contacts as customers in QuickBooks so invoices can be sent to the correct people with accurate billing information.

Can you modify my deals?

No. We only have read access. We cannot change deal amounts, stages, or any properties.

Do you access custom properties?

We access only standard properties needed for invoicing. Custom properties are generally not accessed unless specifically needed for customer sync.

Why do you need line items access?

To calculate accurate invoice totals including itemized products, quantities, and discounts from your deals.

Can you create quotes?

No. We only have read access to quotes to validate that quotes are signed before creating invoices.

Will you access all my contacts?

We only access contacts when needed (e.g., when you create an invoice). We don’t download or continuously poll your contact database.

Can I grant only some scopes?

No. All scopes are required for the integration to function. It’s an all-or-nothing approval.

Can scopes be changed after installation?

Scopes are set during installation. To change them, you would need to uninstall and reinstall (though the same scopes would be requested).

Additional Resources

• OAuth Approval Guide - Detailed explanation of OAuth approval process
• Data Sharing Reference - Comprehensive data flow documentation
• Security Best Practices - Token encryption details
• HubSpot OAuth Documentation  - Official HubSpot OAuth scopes reference