Docs

Orgs: run Unbrowse for your own users

For teams that build agents for other people: agencies, forward-deployed engineers, and products with an AI assistant. You hold one account, one key and one bill. Each of your users gets their own logins and sessions, and a site one of them teaches Unbrowse works for all of them.

Console: unbrowse.ai/app/org.

How it works

Your users never create an Unbrowse account. You never handle their passwords, and neither does your model.

1. Create the org and a key

Sign in at https://unbrowse.ai/app/org, create the org, then press Mint org key. Or over REST, signed in or with a personal key:

curl -X POST https://unbrowse.ai/api/v1/org \
  -H "Authorization: Bearer $PERSONAL_KEY" -H "content-type: application/json" \
  -d '{"name": "Acme", "appName": "Acme Assistant", "domain": "acme.com"}'

curl -X POST https://unbrowse.ai/api/v1/org/keys -H "Authorization: Bearer $PERSONAL_KEY"
# → { "id": "key_…", "prefix": "ub_live_…", "token": "ub_live_…" }   (shown once)

• domain is optional. It must match the domain you signed in with, cannot be a free-mail domain (gmail.com, outlook.com, …), and belongs to one org only.
• Only a person mints org keys. An org key calling POST /org/keys gets 403, so a leaked key cannot mint its own replacements.

2. Call as your user

MCP (Streamable HTTP):

{
  "mcpServers": {
    "unbrowse": {
      "url": "https://unbrowse.ai/mcp",
      "headers": {
        "Authorization": "Bearer ub_live_…",
        "X-Unbrowse-End-User": "user_8421"
      }
    }
  }
}

REST:

curl https://unbrowse.ai/api/v1/runs \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "X-Unbrowse-End-User: user_8421" \
  -H "content-type: application/json" \
  -d '{"task": "my open pull requests on github", "idempotencyKey": "pr-1"}'

• The user id is yours: 1–128 characters from letters, digits and _ . : @ -. Use a stable internal id, not an email you might change.
• The same id under two different orgs is two different people.
• Without the header, the org key acts as the org itself (useful for testing; the org's own logins are not any user's).
• The header is X-Unbrowse-End-User. Not X-Unbrowse-User: the edge strips that one from every request (it carries Unbrowse's own signed sign-in).

Clients that cannot send headers (some hosted MCP clients): mint a key for one user and put it in that user's config.

curl -X POST https://unbrowse.ai/api/v1/org/users \
  -H "Authorization: Bearer $ORG_KEY" -H "content-type: application/json" -d '{"user": "user_8421"}'
# → { "workspaceId": "ws_…", "user": "user_8421", "token": "ub_live_…" }

A per-user key only ever acts as that user. It cannot select another user with the header.

3. When a site needs your user's login

A run refused for sign-in, where the user has no saved login for that site, returns a link instead of guessing:

{ "status": "failed",
  "error": { "code": "session_or_permission", "message": "…" },
  "signIn": { "url": "https://unbrowse.ai/connect/cr_…", "requestId": "cr_…", "origin": "https://github.com",
              "message": "…" } }

(mfa_required is the other code that carries signIn.)

unbrowse_credentials_request {origin, reason} creates one on demand; unbrowse_credentials_status {requestId} reports pending, fulfilled, declined or expired.

Send the link to that user (chat, email, in-app). The page says "Acme Assistant wants to use your github.com account" with the reason. They sign in there, or press Don't connect. Once unbrowse_credentials_status says fulfilled, call again with the same input.

• The link is the only authority: the user needs no Unbrowse account. It works once and expires after 30 minutes.
• The login is sealed (AES-256-GCM, per-workspace key) in that user's workspace only. Your other users, your org key and your model never see it; runs fill it into the site's own login form.
• A wrong, used, declined or expired link saves nothing.
• Kept sessions are reused, so the user is not asked again until the site logs them out.

4. One bill

• Every verified call by any of your users is charged to the org: the org's monthly free allowance first, then its paid credits (1 credit = one verified call = $0.001). Failed, refused and challenged calls are free.
• When both are empty, calls get 402 quota_exceeded with a top-up link. Adding user ids never adds allowance.
• Top up from /app/org (Stripe packs of $10, $50, $200). The org page shows calls per user this month.
• GET /api/v1/usage as a user returns the org's balance with paidBy: "org" and that user's own calls under own.

5. Tools your users share

When one of your users runs a site Unbrowse had to learn, the route is shared with your other users, so their first call is fast too:

• Only read-only routes that need no login or secret are shared, scrubbed exactly as for the public registry: no recorded traces, no search terms or other user values, no cookies.
• Shared tools appear as org__<site>__<tool> in discovery, tool lists and /api/v1/sites/<host>, for your users only. Other orgs and everyone else never see them.
• They reach the public registry only if you turn on Also share them with everyone on Unbrowse (POST /api/v1/org/settings {"sharePublic": true}). Off by default.
• Anything that signs in or changes a site stays in the one user's workspace.

REST reference

Every other endpoint (/runs, /sites/..., /usage, MCP tools) takes the org key plus X-Unbrowse-End-User.

Errors

Not yet

Leaving an org, removing a member, transferring ownership, per-user spending caps, custom domains, and hiding the Unbrowse name. The connect page says "secured by Unbrowse".