Appearance
Allowed IP addresses
An OAuth app can have a list of IP addresses it may be used from. A request from any other address is refused, even with a valid token. If someone steals your API credentials, they cannot use them from outside the networks you allow.
This is a TenkeyBridge extension
QuickBooks Online has no per-app network limit. An app written for QBO needs no change. Apps you already created have no list and accept any address until an organization admin sets one.
What it covers
The list belongs to the OAuth app (one list per app, the same for every company connected through it). It is checked on:
- Every API call made with an access token:
/v3/company/..., including/batch, reports,/entitlementsand/clearedstatus. - The token endpoint,
POST /oauth2/v1/tokens, for both the code exchange and the refresh. A refused call does not use up the authorization code or the refresh token, so fixing the list is enough.
It is not checked on the connect page (/authorize), because that is your user's browser and not your server, or on /revoke, because revoking a token from anywhere is always safe.
Set it up
Portal
Open the app in the developer portal, find Allowed IP addresses, enter one address or range per line, and save. You are asked to confirm, because calls from any other address will fail, including your token refresh. To go back to accepting any address, clear the list.
Admin API
bash
curl -X PUT https://api.tenkeybridge.com/admin/v1/clients/CLIENT_ID/allowed-ips \
-H "x-api-key: $TKB_API_KEY" -H "content-type: application/json" \
-d '{ "allowedIps": ["203.0.113.7", "198.51.100.0/24", "2001:db8::/48"] }'The reply returns the list as stored. GET on the same path reads it. An empty array (or null) clears it. See Admin API.
Rules for entries
- A single IPv4 or IPv6 address, or a CIDR range such as
198.51.100.0/24. - At most 50 entries. Use ranges to cover more.
0.0.0.0/0and::/0are refused: a range that matches everything does nothing. To allow any address, clear the list.- Addresses are tidied up when saved: IPv6 is lowercased and shortened, a range is reduced to its network address, and
::ffff:203.0.113.7is stored as203.0.113.7. - Private ranges (
10.x,192.168.x,172.16.xto172.31.x) and loopback (127.x,::1) are accepted but never match real traffic, because TenkeyBridge sees your server's public address. The portal warns you.
Find your server's outbound IP address
The address that counts is the public address your server uses to reach api.tenkeybridge.com. From the server itself, run:
bash
curl https://api.ipify.orgIf you run more than one server, allow each of their addresses, and ask your host whether the address is fixed. Your own laptop or browser address is not the same thing, so the portal has no "use my IP" button.
Serverless hosts
Hosts such as Vercel and AWS Lambda usually send requests from a changing pool of addresses, so there is no single address to allow. Either leave the list empty and rely on a restricted key, or route the calls through a fixed outbound address (a NAT gateway or a static-IP add-on from your host) and allow that address.
When a request is refused
An API call returns 403 with an AuthorizationFault and code IP_NOT_ALLOWED:
json
{
"Fault": {
"Error": [{
"Message": "Request IP is not on this app's allow-list",
"Detail": "The request came from 198.51.100.9, which is not on the allow-list of \"Billing sync\". ...",
"code": "IP_NOT_ALLOWED"
}],
"type": "AuthorizationFault"
}
}The token endpoint answers 400 with the standard OAuth error unauthorized_client, a description that names the address, and "tkb_code": "IP_NOT_ALLOWED".
Do not refresh the token or send the user through the connect flow again. The answer will not change until the list or the caller's address does. Nothing was sent to QuickBooks.
If a request has no readable source address while a list is set, it is refused too.
Refused calls appear in the request log with the error code IP_NOT_ALLOWED. The log does not store IP addresses.
How it fits with other limits
Three independent limits stack, and a call must pass all of them:
- Allowed IP addresses (this page): where the credential may be used from.
- Restricted keys: what the credential may do, and on which records.
- A restricted QuickBooks user: what the QuickBooks user TenkeyBridge runs as may do inside your company file. A refusal there is
QB_PERMISSION_DENIED.
With all three, a stolen credential used from outside your network is refused first; one used from inside is limited to the app's access; and QuickBooks still enforces its own user rights.
Admin API keys are not covered by the allowed IP list. They manage your account, not your company file. Keep them out of integrations.
Client library
@tenkeybridge/client throws IpNotAllowedError for both the API call and a refused token refresh. definitelyNotApplied is always true and the library never retries it.
ts
import { IpNotAllowedError } from "@tenkeybridge/client";
try {
await client.invoice.read("123");
} catch (err) {
if (err instanceof IpNotAllowedError) {
// Fix the app's allowed IP addresses; do not re-authorize.
}
}Operators
IP_ALLOWLIST_ENFORCE=false turns every check off. See Gateway operations.

