Appearance
Developer portal
The portal is a browser UI over the Admin API — every action below is a click on the exact same /admin/v1 endpoints you could otherwise script against. If you'd rather automate provisioning than click through it, the Admin API doc is the complete reference; this guide walks the same ground by hand.
Where this fits
The portal is at https://api.tenkeybridge.com/portal (exactly /portal, no trailing slash). Sign in with an email and password, a magic link, or a configured sign-in provider.
Sign in
Go to /portal/sign-in. You can get in five ways; use whichever fits.
- Email and password. New here? Click Create an account, enter your email and a password of at least 12 characters, then open the confirmation link we email you. That link signs you in. Until you've confirmed, a password sign-in is refused and the page offers to resend the confirmation.
- Magic link. Click Email me a sign-in link (its own page at
/portal/sign-in/link), enter your email, and open the link that arrives. No password involved. - Google, GitHub, or Apple. A button appears for each provider the gateway has credentials for. Signing in with a provider that uses the same verified email as an existing account lands you in that account, not a second one.
Forgot your password, or never set one? Click Forgot password? (or go to /portal/forgot-password). Enter your email; if it has an account, a reset link arrives within a minute and is good for an hour. Choosing a new password signs you out everywhere, then returns you to the sign-in page. Magic-link users use this same path to add a password to their account.
If you try to create an account with an address that already has one, the page looks the same either way (so nobody can probe which emails are registered), and the existing owner gets an email pointing at sign-in and password reset.
Create an organization
Every company, OAuth app, Web Connector connection, and API key in TenkeyBridge belongs to an organization, not to you personally. The first time you sign in, /portal shows a first-run form instead of an org list: give it a name (say, "ExampleCo") and it derives a URL-safe slug from it automatically (exampleco) — edit the slug field directly if you want something else. Submitting takes you back to the dashboard, now showing your new org as a card.
Signing up this way makes you the org's owner. Roles matter throughout the rest of this guide — see Organizations and roles for what owner, admin, and member can each do.
Click an org's card to enter it. Every page from here on is scoped to that one organization. The org name is the first control in the left sidebar — click it to switch to another org, go back to the full list, or start a new one. The sidebar has five items: Overview, Companies, Logs, Developers, and Settings. Your email, appearance, and Sign out live in the user menu at the bottom of the sidebar. Docs is in the main header.
Appearance is Light, Dark, or System (follow your device), set from the user menu. The choice is remembered in your browser.
Bookmarks and links from the older portal still work: the old Realms, OAuth clients, API keys, Members, and Billing addresses redirect to Companies, Developers, and Settings, keeping any query string.
Overview
Entering an org lands you on Overview. It is a dashboard for the whole organization, read live every time the page loads:
- A Get started checklist until you're set up: add a company, connect QuickBooks to it, create an OAuth app or an API key, invite a teammate (optional), and billing. Each row shows what's done and, if your role can act on it, a button that goes to the right page. A
membersees the same status with no buttons. - Four tiles: Companies connected, Calls (24h) with a small trend line, Error rate (24h), and Median latency (24h). A brand-new org shows a dash instead of a percentage or latency.
- A Companies card listing each company with its status, and a Recent failures card with the latest failed requests ("No errors in the last 24 hours" when there are none).
If one card can't load, it shows an inline error with Retry and the rest of the page still renders.
Companies
A company is one QuickBooks company file. Everything you query or write is scoped to a company; its Company ID is the {realmId} in every /v3/company/{realmId}/... URL (the Admin API and URLs still call it a realm). Open Companies for the list.
Each row shows the company's name, its Company ID with a copy button, its type, how it connects, its last check-in, and calls in the last 24 hours. The status dot reads:
- Online — checked in within the last 5 minutes.
- Recent — within the last 24 hours.
- Stale — no check-in for more than 24 hours.
- Never — QuickBooks has never connected.
Sandbox companies carry a Sandbox badge instead of a dot. The list is sorted with problems first (stale, never), then the busiest. Use the search box and the Type and Status filters to narrow it down.
Your sandbox
Every organization starts with a sandbox company, listed with a Sandbox badge and named after the organization (for example ExampleCo Sandbox). It answers the API from sample data, so you can build before connecting QuickBooks. Its Settings tab shows today's call count and record count against the limits, plus a Reset sandbox button (you type the sandbox's name to confirm and choose the sample or empty template). See Sandbox.
Add a company and connect QuickBooks
Click Add company (visible to admin and owner; a member can view the list but not add). A short wizard walks you through it:
- Name — for a real company this is usually the QuickBooks company's name, e.g. "ExampleCo Plumbing".
- Connect — choose how QuickBooks will reach TenkeyBridge. Web Connector is the default and installs nothing. (An agent option appears only when the gateway has it enabled.)
- Download & copy — a
.qwcfile downloads and a one-time password is shown. Copy the password before continuing; it is never shown again. On the machine running QuickBooks, open the.qwcin QuickBooks Web Connector (Add an Application), choose Yes, always; allow access even if QuickBooks is not running, paste the password, and tick Auto-Run. - First check-in — the wizard waits and confirms the moment Web Connector checks in for the first time.
The full walkthrough, including how the company file gets pinned, is in Connect QuickBooks; on Rightworks follow the Rightworks guide instead.
A company's tabs
Click a company to open it. The header shows its name, Company ID, and status, and the page has three tabs:
Connection — the Web Connector connections for this company. Per connection (
admin/owner):- Download .qwc re-downloads the
.qwcfile at any time; it never contains the password. - Reset password issues a new one-time password for that connection (click it twice to confirm); the old password stops working. Copy the new one before dismissing.
- Send setup emails the
.qwcand setup steps to your QuickBooks admin or whoever runs the machine — handy for hosted desktops. It never includes the password; use Reset password to hand that over separately. - Unpin file lets the next session re-pin if the company file legitimately moved.
- Revoke stops the connection: Web Connector's next poll fails until you add a fresh connection and its new
.qwc. A revoked row offers only Delete.
If agent connections are enabled for the gateway, an Agent connections card with Add agent connection appears below.
- Download .qwc re-downloads the
Activity — this company's requests, using the same view as Logs.
Settings — Rename, the company's departments (see Departments), the sandbox's usage and Reset sandbox (sandbox companies only), and a Danger zone with Delete company.
Deleting a company
Only an org's owner can delete a company — admin and member never see the option. Open the company's Settings tab, click Delete company under Danger zone, and type the company's name to confirm.
Deleting a company:
- Revokes every OAuth token, OAuth code, and Web Connector connection issued for it — Web Connector's next poll for that username is rejected (
nvu); a session already in progress is not force-closed - Cannot be undone — there's no recovery, and no soft-delete/restore
Once deleted, the Web Connector entry on the QuickBooks machine keeps polling with a username that no longer exists and shows nvu in its Status column — remove that entry from Web Connector, or add a fresh .qwc from another company. For example, if ExampleCo deletes its ExampleCo Sandbox, any app still holding an OAuth token scoped to it starts getting 401s immediately.
Logs
Logs lists the API requests across the whole organization, newest first. Filter by Company, Status (success, client error, server error), Error code, Entity, OAuth app, and Range (last hour, 24 hours, 7 days, or a custom range up to 90 days back). The filters live in the URL, so you can share or bookmark a filtered view.
Click a row to open Request details: request ID, time, company, method and path, status, duration, QuickBooks and queue wait, request and response sizes, the OAuth app, the transport, and, for errors, a plain-language explanation of what the error means and what to do next. Payloads aren't stored — only sizes and timings are kept, never the request or response bodies.
Developers
Developers holds what your code uses to call TenkeyBridge: the API base URL (with a copy button), your OAuth apps, and your API keys. Creating either needs admin/owner.
Register an OAuth app
Click New OAuth app. Give it a name and one or more redirect URIs, one per field (Add URI adds another, up to 10) — the same validation the Admin API enforces applies here (https://..., or plain http://localhost for local dev; see the client rules in the Admin API doc) — and submit.
An OAuth app is the credential for calling QuickBooks data: the QBO-compatible authorize/token flow gets a bearer token for /v3. Use it for a product you ship to others, or for your own scripts and MCP servers.
The client secret is shown once: copy it, with the client ID, into your app's OAuth configuration before dismissing. The list never shows the secret again — only the client ID and redirect URIs, which you can edit later from the row's menu (Edit redirect URIs — the form replaces the whole list, it doesn't merge into it) or delete outright. Deleting an app immediately disconnects every company that authorized through it.
Mint an API key
Click New API key and give it a short name (32 characters max). The key — prefixed tkb_ — is shown once, the same way. Send it as the x-api-key header on /admin/v1 calls instead of a session cookie; it's scoped to this one organization for its whole life. Reading or writing QuickBooks data always goes through an OAuth app's token instead.
A key mints with the permissions of whoever created it, at whatever role they currently hold — not a fixed role baked in at mint time. It also can't be used to mint or revoke other keys, even by an owner's key; that always requires a signed-in session.
Settings
Settings has two tabs: Members and Billing.
Invite a teammate
On Members, if you're admin/owner, fill in Invite member: an email address and a role of admin or member (the portal never offers owner — that's reserved for whoever created the org). Submitting sends an invitation email and adds a row to Pending invitations, with a Re-invite button if it needs resending.
The invite email links to /portal/accept-invitation/<id>. Opening it while signed in accepts the invitation and lands back on the dashboard with the new org visible; if you're not signed in yet, the portal sends you through sign-in first and brings you right back.
From the members table you can change anyone's role between admin and member, or remove them — except the org's owner, whose row has no controls to demote or remove them.
Billing
The Billing tab shows the org's plan, 30 days of usage, and manages its subscription. This page is a thin front end over the same GET /admin/v1/orgs/:orgId/billing and POST .../billing/checkout / POST .../billing/portal-session endpoints described in Admin API: Billing — see the billing guide for the plans themselves and how metering and enforcement work.
The plan card shows the plan (Trial / Production / Enterprise), a status pill, and — for Trial — how many of the plan's one connection you're using; for Production, the connected company-file count and the $44.99/mo rate. The usage section shows the last 30 days of API requests and errors as a totals line plus a per-day bar strip.
Any member can view this page; the action underneath it is admin/owner only:
- No active subscription → a Subscribe button, which opens Stripe Checkout for the plan.
- An active or past-due subscription → a Manage billing button, which opens the Stripe Billing Portal (update payment method, change plan, cancel, view invoices).
- Enterprise plan → a Contact sales link (
sales@tenkeybridge.com) instead of either button — Enterprise is arranged off-platform.
Returning from Stripe Checkout lands back on this page with a Subscription started or Checkout canceled notice, depending on how you left.
If the gateway has no Stripe configuration at all, the page says "Billing is not configured on this gateway." and shows no button, for every role.
Secrets are shown once
Three kinds of secret only ever appear once, right when you create them, exactly as the Admin API describes in Things that are shown once:
- OAuth client secrets, when you create an OAuth app
- Web Connector passwords, when you add a company or a connection, or reset a password
- API keys, when you create one
Every list and detail view that shows the parent resource — the OAuth app table, the Web Connector table, the API-key table — omits the secret value entirely. The portal's one-time modal (monospace text, a Copy button, and an explicit "I've stored it" button you have to click to dismiss it) is the only place any of these ever render. If you lose one, there's no recovery: issue a new one (for a Web Connector connection, Reset password) and revoke the old.
What's not here yet
The portal covers organizations, companies, Web Connector connections, OAuth apps, API keys, request logs, membership, and billing — the same ground as the Admin API.

