Vault Spaces — the reference tenant app

Build a private, agent-backed Spaces app on Witbitz, as a tenant. Spaces — the flagship multiplayer AI room — is the reference app: you register a tenant, embed the reference Spaces, then deploy and verify it. Every step below is a real, exact operation you can run now.

Get Started path: this → Deploy it → Verify it. Reference: Platform API (OpenAPI) · The SDK.

Quickstart — paste into an Ubuntu terminal

Want it running now? This registers a tenant and turns an agent config into a live Space hosted on Witbitz — no file to write, no server to run, no deploy. Needs only curl and python3 (both standard on Ubuntu).

# 1) Register a free demo tenant — your builder identity on the platform (keys shown once; you'll need it for Deploy & attribution).
resp=$(curl -sX POST https://api.witbitz.chat/v1/tenants/demo \
  -H 'content-type: application/json' -d '{"name":"My first Space"}')
export WSK=$(echo "$resp" | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["keys"]["secret"])')
echo "Tenant secret key (save it — shown once): $WSK"

# 2) Turn an agent config into a LIVE Space, hosted on Witbitz — then open the link it prints.
cfg=$(printf '%s' '{"agentName":"Helper","persona":"You help a small group plan and decide together."}' \
  | base64 | tr '+/' '-_' | tr -d '=\n')
echo "Your live Space: https://witbitz-spaces.pages.dev/embed-create#cfg=$cfg"

Open that URL and chat. It mints a fresh private room from your config and serves it — all on the Witbitz origin, with no page to host and no backend. The room is private by key-possession (the key rides the link fragment, never a server), and the config (name + persona) travels in the # fragment, so the server never sees it in the clear. Change the persona and re-run to reshape the agent.

This room is public — anyone with the link can open it (that's what "no secret in the flow" means). When you want rooms attributed to your tenant, two paths open up — both using the tenant you just registered:

• Deploy on your own origin — a page you host embeds this same config from an origin you've declared.
• A bespoke Witbitz-hosted app — Witbitz provisions your tenant its own full deployment: own origin, own key vault, own split-key ecosystem key, your config baked in, sign-in included (what you get).

Then verify it. The rest of this page explains each piece.

1. Register a tenant

You build as a tenant — your builder identity on the platform. Get a key pair with no invite using the demo path:

curl -sX POST https://api.witbitz.chat/v1/tenants/demo \
  -H 'content-type: application/json' \
  -d '{"name":"My app"}' | python3 -m json.tool

Response (201, Cache-Control: no-store):

{ "data": {
  "tenant": { "tenant_id": "t_…", "status": "active", "roles": ["app"], "expires_at": "2026-09-24T…Z" },
  "keys":   { "secret": "wsk_…", "publishable": "wpk_…" }
} }

• wsk_… — your secret key: server-side only, full scope, shown once — store it now (only its hash is kept).
• wpk_… — publishable: browser-safe, identifies your tenant; it does not authenticate an end user.
• expires_at — a demo tenant is real and works immediately, but auto-purges at that time unless you keep it.

No coupon needed to follow this walkthrough — the demo tenant works as-is. It only auto-purges at expires_at; when you're ready to make it permanent (same id + keys), see Keep your tenant.

Calling the API. Base URL https://api.witbitz.chat/v1; present your secret key as Authorization: Bearer wsk_…. Success is enveloped { "data": … }, errors { "error": { "code", "message" } }. The OpenAPI is canonical — point tooling at https://api.witbitz.chat/v1/openapi.json (Platform API). Confirm your tenant:

curl -s https://api.witbitz.chat/v1/tenant -H "Authorization: Bearer wsk_…" | python3 -m json.tool

2. Build the app — embed the reference Spaces

Your app is the reference Spaces, embedded. Two lines put the verified Spaces room on any page:

<script src="https://witbitz.chat/embed.js"></script>
<witbitz-space link="https://witbitz.chat/space#<your link>"></witbitz-space>

No link yet? Mint a room inline from a config — no pre-creation, no key handling on your page:

<div id="slot" style="height: 600px"></div>
<script src="https://witbitz.chat/embed.js"></script>
<script>
  // Your agent config, base64url-encoded into the link fragment (after #, so it never reaches the server).
  const config = {
    agentName: 'Helper',
    persona: 'You help a small group plan and decide together.',
  }
  const cfg = btoa(JSON.stringify(config))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '')

  const space = Witbitz.embed('#slot', {
    link: `https://witbitz-spaces.pages.dev/embed-create#cfg=${cfg}`,
    tools: {
      // A function on your page becomes a tool the agent can call.
      set_site_color: (args) => { document.body.style.background = args.color },
    },
  })

  // Turn metadata only — never message content.
  space.on('message', (msg) => console.log(msg.id, msg.self))
</script>

That last block is the pattern: a function on your page becomes a tool the agent can call. Witbitz.embed() also returns signIn, ask, invoke, setTheme, setState, and destroy — see embed.

Configure the agent — the same sealed config either way (the server never sees it in the clear):

How the tenant and the room fit. The embedded Space runs on the Witbitz origin and authenticates by key-possession — the room key rides the link fragment, never your page and never your tenant key. Your tenant is your identity on the platform (/v1): it meters usage to you and unlocks the platform surface (collections, sessions, agents). So the room is private by key-possession; the tenant is how the platform knows the app is yours.

Next

• Deploy it — host your page on your own branded origin.
• Verify it — confirm the deployed Space is exactly what it claims.
• Reference: Platform API (OpenAPI) · The SDK.

Machine-readable source: vault-spaces.md · Generated 2026-08-29T18:46:30Z · build f3ff88cc · every doc in one fetch: llms-full.txt (HTML) · ← platform · deploy →