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). During early access the entire portal — and the /admin/v1 surface it calls — sits behind an HTTP Basic prompt (your browser will ask for it once per session) as a stopgap until sign-up is public. Ask for the early-access credentials if you don't have them yet.

Sign in

Go to /portal/sign-in. At launch the way in is a magic link: enter your email, click Send magic link, and open the link from the email that arrives — it signs you in and returns you to the page you started from. There's no password to set.

Google and GitHub buttons render on this page once those providers are configured on the gateway; they aren't at launch, so magic link is the path to use for now.

Create an organization

Every realm, OAuth client, agent token, 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.

Create a realm and connect the agent

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.
• An Agent online / Agent offline badge, live from the gateway's connection to that realm's edge agent.
• A table of agent tokens issued so far, with an issue-token form below it.

Click Issue token, optionally labeling it (e.g. "front office"), and submit. The token is shown to you exactly once, in a modal, alongside a ready-to-paste config snippet:

{
  "GatewayUrl": "wss://api.tenkeybridge.com/agent",
  "AgentToken": "tkba_xxxxxxxx…",
  "CompanyFile": ""
}

Copy the token (or the whole snippet) before dismissing the modal — there is no way to see it again from the portal; issue a new one if you lose it. Paste it into the agent's appsettings.json as AgentToken, fill in CompanyFile with the path to your .qbw file (or leave it empty to use whatever company file QuickBooks has open), and follow the rest of the install from Edge agent — install & setup. Once the agent connects, the badge on this page flips to Agent online.

Revoking a token is a button on its row (admin/owner only) — the agent using it stops authenticating on its next connection attempt.

Register an OAuth client

Open OAuth Clients and click Register client (admin/owner). Give it a name and one or more redirect URIs — 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 agent token: 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 (the edit 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.

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
• Agent tokens, when you issue one 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 agent-token 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.

What's not here yet

The portal covers organizations, realms, agent tokens, OAuth clients, API keys, and membership — the same ground as the Admin API. It does not yet have a usage dashboard, an in-portal agent installer download, or billing; none of that exists today.