Skip to content

Restricted keys ​

A restricted key is an OAuth app whose access you limited to what the integration needs. You choose what the app may do (read, create, update, delete, void, send) and on which records (invoices, payments, lists, reports and so on). Anything outside that is refused by the gateway with 403 SCOPE_DENIED before a single request reaches QuickBooks.

This is a TenkeyBridge extension

QuickBooks Online has one coarse scope, com.intuit.quickbooks.accounting, and no per-entity or per-action limits. An app written for QBO needs no change: it sees only a new 403 SCOPE_DENIED fault, which has the standard AuthorizationFault shape. Apps you already created keep full access until an organization admin chooses otherwise.

Why restrict a key ​

Least privilege. A reporting dashboard does not need to void invoices, and a billing sync does not need to read payroll. If the credential leaks, the damage is limited to what you allowed. See What a stolen credential can do.

Presets ​

PresetAllowsTypical use
Read onlyread on everything, including reportsDashboards, BI, AI assistants
No deletes or voidsread, create, update, sendSync jobs that should never destroy records
Full accessAll six operationsThe default for existing apps
CustomExactly the rules you pickAnything in between

In the portal the preset is called Access and is chosen when you create the app. Pick it on purpose: the create dialog does not preselect one.

Operations ​

OperationWhat it covers
readGET of one record, queries (GET /query), GET /pdf, CDC feeds, reports
createPOST /{entity} without an Id
updatePOST /{entity} with an Id, or ?operation=update (sparse and full updates, line edits)
deletePOST /{entity}?operation=delete
voidPOST /{entity}?operation=void
sendPOST /{entity}/{id}/send

Operations are not HTTP verbs, because QBO uses POST for both create and update.

Update versus send

send is only the /send action. Setting EmailStatus: "NeedToSend" through an update is an update, so it needs update on that entity. If a key must never queue an email, do not give it update on that entity.

Records and groups ​

A rule names an entity (Invoice), a group, or * for everything. Groups keep custom rules short.

GroupEntities
@salesInvoice, Estimate, SalesReceipt, CreditMemo, RefundReceipt
@paymentsPayment, BillPayment, Deposit, CreditCardPayment, ReimburseCharge, TaxPayment
@purchasingBill, VendorCredit, PurchaseOrder, Purchase
@bankingTransfer, JournalEntry, InventoryAdjustment, JournalCode
@listsCustomer, Vendor, Employee, Item, Account, Class, Department, TaxCode, TaxRate, TaxAgency, TaxClassification, Term, PaymentMethod, CustomerType, VendorType, Tag
@companyCompanyInfo, Preferences, CompanyCurrency, ExchangeRate, Budget, TimeActivity, Attachable, RecurringTransaction

Three surfaces are not one entity, so they are named on their own:

NameSurface
ReportEvery report under /reports. A report reads across all records, so it is its own switch.
ClearedStatusGET (read) and POST (update) of /clearedstatus
TaxServicePOST /taxservice/taxcode (create)

How each route is checked:

RequestNeeds
GET /queryread on the entity in the FROM clause
GET /cdc?entities=A,Bread on each listed entity. One missing entity refuses the whole request.
GET /reports/{name}read on Report
GET /exchangerateread on ExchangeRate
POST /batchEach item as above, see Batch
GET /entitlementsAlways allowed. It describes what the caller may do.

Internal lookups the gateway does on your behalf (fetching a SyncToken before an update, resolving a customer or item reference) are not checked. The unit of restriction is the surface you name: a create on Invoice does not need read on Customer, and a read of an invoice still returns the customer name inside it.

Set it up ​

Portal ​

Open Developers, then OAuth apps. Choose an Access card when you create the app, or use Edit access on an existing one. Widening access asks you to confirm. The app list shows each app's access and how many calls it had denied in the last 24 hours.

Admin API ​

Create an app with a preset:

bash
curl -s -X POST https://api.tenkeybridge.com/admin/v1/clients \
  -H "x-api-key: $TKB_API_KEY" -H "content-type: application/json" \
  -d '{"orgId": "org_abc123", "name": "ExampleCo reports", "redirectUris": ["https://app.exampleco.example/cb"], "preset": "read_only"}'

Or a custom allow-list:

json
{
  "policy": {
    "preset": "custom",
    "rules": [
      { "entity": "*", "ops": ["read"] },
      { "entity": "@sales", "ops": ["create", "update"] }
    ]
  }
}

Change it later with PATCH /admin/v1/clients/{clientId}/policy (org admin). The change applies to the very next request, with no re-consent and no new tokens. See the Admin API.

Limit one company ​

An app works with every company in its organization. To narrow it for one company (for example "Acme Co may only be read"), use Company limits on the app in the portal, or PUT /admin/v1/clients/{clientId}/realms/{companyId}/policy. A company limit can only narrow: a call must be allowed by the app and by the company limit.

What a stolen credential can do ​

A client secret, access token (1 hour) or refresh token (100 days) acts with the app's access and only on companies of its own organization. Until you revoke the app (delete it in the portal), a thief can do:

PresetA stolen credential can
Read onlyRead the company file, including reports. It cannot change anything.
No deletes or voidsRead, and create or update records. It cannot delete or void, but can still add or alter.
Full accessRead, change, delete and void everything in your companies.
CustomExactly the rules you set.

You can also limit where a stolen credential works at all: an app can have a list of allowed IP addresses, and a call from any other address is refused with IP_NOT_ALLOWED, whatever the app's access.

To recover, delete the OAuth app (this disconnects every company connected through it) and create a new one with the access it needs. Watch for bursts of SCOPE_DENIED from one app, which is what a stolen key probing for access looks like.

Admin API keys are not limited by this

Admin API keys manage your account (companies, OAuth apps, other keys) and are not restricted by an app's access. A leaked admin key can create a new, unrestricted OAuth app. Restrict the OAuth app your integration uses and keep admin keys out of integrations.

When a customer connects a company, the consent page lists what the app can do in plain words, for example "Read accounting data, but not change it". The scope parameter is accepted for QBO compatibility and is informational: the grant is whatever the app's access allows.

Client library and MCP ​

@tenkeybridge/client 0.9.0 adds client.access() (what this credential may do) and a ScopeDeniedError. @tenkeybridge/mcp 0.9.0 hides the tools a key cannot use. See the Node.js client.

Troubleshooting SCOPE_DENIED ​

403 SCOPE_DENIED means the app is valid but the request is outside its access. The Detail names the entity, the operation and the app, and lists what it may do.

  1. Read the Detail: which entity and operation was refused?
  2. Ask an organization admin to widen the app's access, or use an app that has it.
  3. Do not retry or refresh the token. The answer does not change until the restriction does, and nothing was sent to QuickBooks, so there is nothing to reconcile.

A QB_PERMISSION_DENIED is a different problem: the QuickBooks user behind the connection lacks a permission in QuickBooks. See Error codes.

TenkeyBridge is an independent product, not affiliated with, endorsed by, or sponsored by Intuit Inc. QuickBooks, QuickBooks Online, and QuickBooks Desktop are trademarks of Intuit Inc., used only to describe compatibility.