Twin Browser
Get an API key
PlatformOverviewHow it worksAll toolsREST APIMCP serverIntegrationsDocs
CapabilitiesSemantic dispatch cacheDeterministic replayCross-tenant skill corpusToken-efficient DOMHuman-in-the-loopLive view & videoCredential vaultOverviewSolutions
SolutionsAll use casesAI agentsRPA replacementQA & test automationData extraction
ResourcesGuidesGlossaryBlogCompareFAQStatus
Pricing
Log in

CAPABILITY · RESELLER

Provision a customer, mint their key, choose who pays

One scoped call creates a sub-tenant under your account and returns its API key — billing either to its own balance or to your pool, with every charge attributed.

Start freeAPI reference
POST /api/v1/tenants

Capability

Inside sub-tenants & reseller billing

If you are embedding browser automation in your own product, your customers are tenants of yours, not of ours. Sub-tenant provisioning makes that structural: one call creates the tenant, mints its API key and decides the billing relationship. Either the sub-tenant pays from its own balance — which you can seed with an opening grant — or your pool pays and every charge is attributed back to the sub-tenant that made it.

Two billing modes

"self" gives the sub-tenant its own balance, optionally funded by a grant transferred from yours. "parent" bills your pool, with each charge attributed to the sub-tenant that incurred it.

The key is shown once

Provisioning returns the sub-tenant's API key in the 201 response and never again. Store it when you receive it.

Scoped, not implicit

Provisioning requires the tenants:provision scope on the calling key. A key without it gets 403 — the capability is not switched on by simply having an account.

Visible economics

GET /api/v1/tenants lists your sub-tenants with their balances and what they have billed to you, so a parent-billed fleet is not an unmeasured cost.

How it works

The mechanism, in execution order

4 stages, in the order the runtime performs them — not a summary of them.

  1. 1Get a provisioning keyThe calling key needs the tenants:provision scope. Reseller keys carry it; a default key does not.
  2. 2Create the sub-tenantPOST /api/v1/tenants with a name and a billing mode. Add `credits` to transfer an opening grant (self-billed only).
  3. 3Store the keyThe 201 response carries the sub-tenant's API key once, plus its id, name, slug, plan and billing mode.
  4. 4Watch the ledgerGET /api/v1/tenants returns each sub-tenant with its balance and what it has billed to the parent.

In practice

A call you can paste and run

One call provisions the tenant, mints the key and fixes the billing relationship. The key is never shown again.

tenants.shbash
# The calling key needs the tenants:provision scope — a default key is a 403.
curl -X POST https://twin-browser.com/api/v1/tenants \
  -H "Authorization: Bearer $TWIN_RESELLER_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Acme Corp","billing":"parent"}'
# → 201 {
#     "tenant": { "id":"…", "name":"Acme Corp", "slug":"acme-corp",
#                 "plan":"…", "billing":"parent" },
#     "apiKey": "ab_live_…",     // shown ONCE
#     "granted": 0
#   }

# Or self-billed, with an opening grant from your balance:
#   {"name":"Acme Corp","billing":"self","credits":5000}

# The ledger
curl "https://twin-browser.com/api/v1/tenants" -H "Authorization: Bearer $TWIN_RESELLER_KEY"
# → { "subtenants":[ { "id":"…","name":"…","billing":"parent",
#                      "balance":0,"billed_to_parent":1240 } ] }
api.twin-browser.com
  1. Get a provisioning keydone
  2. Create the sub-tenantrunning
  3. Store the keyqueued
  4. Watch the ledgerqueued

What it costs, how to switch it on

Priced from the same rate card the API serves

Every credit figure on this page is read from the rate card behind GET /api/v1/pricing — it is not typed into the copy, so it cannot drift from what you are billed.

Free to provision — usage bills per the mode

Creating a sub-tenant costs nothing beyond any opening grant you choose to transfer, which moves credits from your balance to theirs rather than spending them. Under "parent" billing, each sub-tenant's usage is charged to your pool at the ordinary rate card and attributed to them. Under "self", they pay from their own balance.

Full rate card

Turning it on

  1. 1Request a reseller keyProvisioning is gated on the tenants:provision scope; a default key carries run, skills:read and skills:write only.
  2. 2Decide the billing mode firstChanging who pays is not a request field on an existing sub-tenant — choose "self" or "parent" at creation.
  3. 3Capture the key immediatelyIt appears once, in the 201. Write it to your own secret store as you read the response.
  4. 4Reconcile from the listGET /api/v1/tenants gives you balances and billed_to_parent per sub-tenant for your own invoicing.

At a glance

The contract, in the fewest rows that say it

PropertyTwin Browser
CreatePOST /api/v1/tenants → 201
ListGET /api/v1/tenants
Required scopetenants:provision
Billing modes"self" (default) · "parent"
Opening grant`credits` — self-billed only
NestingNot supported (409)

Limits

Where it stops, and what it deliberately does not do

A capabilities page with no limits section is a brochure. These are the ceilings, the defaults that will surprise you, and the things this capability is not.

Limits and defaults

  • A key without the tenants:provision scope gets 403.
  • `credits` is only valid on a self-billed sub-tenant; passing it with billing "parent" is a 400.
  • Nested resellers are not supported — a sub-tenant cannot provision sub-tenants of its own (409).
  • An opening grant is transferred from your balance, so provisioning with a grant you cannot cover is a 402.

What it does not do

  • It does not re-show the API key. There is no read endpoint for it.
  • It does not isolate a sub-tenant's skills into yours or vice versa — each sub-tenant is a tenant, with its own library and default-deny row-level security.
  • It does not set per-sub-tenant pricing. The rate card is the rate card; your margin is the difference between it and what you charge.
  • It does not migrate an existing tenant under you.

FAQ

Questions about sub-tenants & reseller billing

Who pays for a sub-tenant's runs?
Whichever you chose at creation. "self" means the sub-tenant spends from its own balance, which you can seed with an opening grant. "parent" means your pool pays and every charge is attributed to the sub-tenant that made it.
How do I get the sub-tenant's API key later?
You do not. It is returned once in the 201 response and never again — store it as you read it.
Can a sub-tenant see my skills or secrets?
No. A sub-tenant is a tenant: its own library, its own vault, its own runs, under default-deny row-level security. The only cross-tenant surface anywhere is the sanitized shared skill corpus.
Can my sub-tenants have sub-tenants?
No — nesting is rejected with a 409. The hierarchy is one level deep by design.

Keep reading

The rest of the platform

The capabilities this one works with, the tools that expose it, the guides that use it end to end, and the vocabulary behind it.

Credential vault

A write-only per-tenant vault: a stored secret is referenced in a goal as {{secret:NAME}}, resolved inside the browser at fill time, and redacted from every step, frame and log.

Skill library & catalog

Every compiled skill is stored per tenant with a version and a run contract — the params it takes, the secrets it fills, and whether your stored auth is ready for its host.

Async jobs & webhooks

Submit a run as a background job and get an id immediately — then poll it, stream its status, or receive an HMAC-signed webhook when it completes.

Tools that expose it

run_goallist_skills

Put your agent to work. Keep the decision.

Start free. Hand your agent a goal on a site you authorize, set the guardrails, and let the first successful run compile the skill every run after it replays.

Start freeRead the docs