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 realm, OAuth client, 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 also has Overview, Realms, OAuth clients, API keys, Members, and Billing. Your email, appearance (light/dark), and Sign out live in the user menu at the bottom of the sidebar. Docs is in the main header.

Overview

Entering an org lands you on Overview, the first sidebar item. It does two things.

The top half explains the four nouns the rest of the portal uses, grouped by which side they belong to — your app uses an OAuth client or API key to call a realm: the credential says who is calling, the realm id in the URL says which company file.

QuickBooks side:

• Realm — one QuickBooks company file. Everything you query or write is scoped to a realm; its realm id is the {realmId} in every /v3/company/{realmId}/... URL. Create one per company file.
• Web Connector — how a realm reaches QuickBooks Desktop: a .qwc file + one-time password added in QuickBooks Web Connector on the machine (or Rightworks desktop) where QuickBooks runs. Nothing to install.

Your app side:

• OAuth client — the credential for calling QuickBooks data: the QBO-compatible authorize/token flow (the same code an app written for QuickBooks Online already has) gets a bearer token for /v3. Use it for a product you ship to others, or for your own scripts and MCP servers.
• API key — an admin-API credential for provisioning from your own scripts: create realms, Web Connector connections, and OAuth clients. Reading or writing QuickBooks data always goes through an OAuth client's token instead.

The bottom half is a live Getting started checklist, read from your own org every time the page loads: create a realm, connect QuickBooks to it, create an OAuth client or an API key, invite a teammate (optional), and billing. Each row shows what is done, one line on why it matters, and — if your role can act on it — a button that takes you to the right tab. A member sees the same status with no buttons.

Overview is also where the org switcher and a freshly created org land, so it is the page you come back to.

Your sandbox

Every organization starts with a sandbox realm, listed under Realms 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 page shows today's call count and record count against the limits, and a Reset sandbox button (you type the sandbox's name to confirm and choose the sample or empty template). See Sandbox.

Create a realm and connect QuickBooks

Inside an org, open Realms and click Create realm (visible to admin and owner; a member can view the list but not create). Give it a name — for a real company this is usually the QuickBooks company's name, e.g. "ExampleCo Plumbing" — and it appears in the table with a generated realm id.

Click through to a realm's detail page and you'll see:

• The realm id, with a copy button — this is the realmId you'll use in /oauth2/v1/authorize and every /v3/company/{realmId}/... call.
• A Web Connector online / Web Connector offline badge, live from the gateway's view of that realm's Web Connector polls, with the pinned company file's name once the first session has run.
• A Connect QuickBooks section: the connections created so far and, for admin/owner, a Create Web Connector connection button.

Click Create Web Connector connection, optionally labeling it (e.g. "front office"). Two things happen at once: a .qwc file downloads, and a modal shows the connection's one-time password — copy it before dismissing; it is never shown again (revoke and recreate if you lose it). Then, on the machine running QuickBooks:

1. Open the .qwc in QuickBooks Web Connector (Add an Application).
2. In QuickBooks' permission dialog choose Yes, always; allow access even if QuickBooks is not running.
3. Paste the password Web Connector asks for, and tick Auto-Run.
4. Within a few seconds the badge on this page flips to Web Connector online.

The full walkthrough, including what each step looks like and how the company file gets pinned, is in Connect QuickBooks; on Rightworks follow the Rightworks guide instead.

Revoking a connection is a button on its row (admin/owner only) — Web Connector's next poll for that username fails, and it stays failed until you create a fresh connection and re-add the new .qwc. Unpin (shown once a company file has been pinned) lets the next session re-pin if the file legitimately moved.

Register an OAuth client

Open OAuth clients and click New client (admin/owner). 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.

The client secret is shown once, in the same kind of modal as the Web Connector password: copy it into your app's OAuth configuration before dismissing. The client list itself never shows the secret again — only the client id and its redirect URIs, which you can edit later from the row's menu (Edit redirect URIs — the form replaces the whole URI list, it doesn't merge into it) or delete outright. Deleting a client immediately disconnects every company that authorized through it.

Mint an API key

Open API Keys and click Mint API key (admin/owner), giving 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.

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.

Invite a teammate

Open Members and, 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

Open an org and click Billing to see its plan, 30 days of usage, and manage 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 register a client
• Web Connector passwords, when you create a connection from a realm's detail page
• API keys, when you mint one

Every list and detail view that shows the parent resource — the client 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 three ever render. If you lose one, there's no recovery: issue a new one and revoke the old.

Deleting a company file

Only an org's owner can delete a company file (realm) — admin and member never see the option. From a realm's detail page, scroll to the Danger zone at the bottom and click Delete company file; click it again within five seconds to confirm, the same two-step confirm used everywhere else in the portal (there's no browser popup to dismiss).

Deleting a company file:

• 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 a different realm. For example, if ExampleCo deletes its ExampleCo Sandbox realm, any app still holding an OAuth token scoped to it starts getting 401s immediately.

What's not here yet

The portal covers organizations, realms, Web Connector connections, OAuth clients, API keys, membership, and billing — the same ground as the Admin API.