Appearance
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
| Preset | Allows | Typical use |
|---|---|---|
| Read only | read on everything, including reports | Dashboards, BI, AI assistants |
| No deletes or voids | read, create, update, send | Sync jobs that should never destroy records |
| Full access | All six operations | The default for existing apps |
| Custom | Exactly the rules you pick | Anything 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
| Operation | What it covers |
|---|---|
read | GET of one record, queries (GET /query), GET /pdf, CDC feeds, reports |
create | POST /{entity} without an Id |
update | POST /{entity} with an Id, or ?operation=update (sparse and full updates, line edits) |
delete | POST /{entity}?operation=delete |
void | POST /{entity}?operation=void |
send | POST /{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.
| Group | Entities |
|---|---|
@sales | Invoice, Estimate, SalesReceipt, CreditMemo, RefundReceipt |
@payments | Payment, BillPayment, Deposit, CreditCardPayment, ReimburseCharge, TaxPayment |
@purchasing | Bill, VendorCredit, PurchaseOrder, Purchase |
@banking | Transfer, JournalEntry, InventoryAdjustment, JournalCode |
@lists | Customer, Vendor, Employee, Item, Account, Class, Department, TaxCode, TaxRate, TaxAgency, TaxClassification, Term, PaymentMethod, CustomerType, VendorType, Tag |
@company | CompanyInfo, Preferences, CompanyCurrency, ExchangeRate, Budget, TimeActivity, Attachable, RecurringTransaction |
Three surfaces are not one entity, so they are named on their own:
| Name | Surface |
|---|---|
Report | Every report under /reports. A report reads across all records, so it is its own switch. |
ClearedStatus | GET (read) and POST (update) of /clearedstatus |
TaxService | POST /taxservice/taxcode (create) |
How each route is checked:
| Request | Needs |
|---|---|
GET /query | read on the entity in the FROM clause |
GET /cdc?entities=A,B | read on each listed entity. One missing entity refuses the whole request. |
GET /reports/{name} | read on Report |
GET /exchangerate | read on ExchangeRate |
POST /batch | Each item as above, see Batch |
GET /entitlements | Always 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:
| Preset | A stolen credential can |
|---|---|
| Read only | Read the company file, including reports. It cannot change anything. |
| No deletes or voids | Read, and create or update records. It cannot delete or void, but can still add or alter. |
| Full access | Read, change, delete and void everything in your companies. |
| Custom | Exactly 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.
The consent page
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.
- Read the
Detail: which entity and operation was refused? - Ask an organization admin to widen the app's access, or use an app that has it.
- 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.

