<!-- Generated 2026-08-29T18:46:30Z · docs build f3ff88cc · authoritative: https://witbitz.chat/docs/vault-spaces.md -->
# 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**](./deploy.md) → [**Verify it**](./verify.md).
> **Reference:** [Platform API (OpenAPI)](./api-reference.md) · [The SDK](./sdk.md).

---

## 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).

```bash
# 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](./deploy.md) 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](./deploy.md#production-notes-for-your-tenant)).

Then [verify](./verify.md) 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:

```bash
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`):

```json
{ "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](./deploy.md#production-notes-for-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](./api-reference.md)). Confirm your tenant:

```bash
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:

```html
<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:

```html
<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](./embed.md).

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

| Field | Meaning |
|---|---|
| `agentName` | Display name (≤ 80 chars) |
| `persona` | System instructions (≤ 4000 chars) |
| `tools` | Platform tools the agent may use — `search_places`, `show_places`, `search_flights`, … ([tools & widgets](./tools-widgets.md)) |
| `immediateTools` | The subset that auto-runs; everything else becomes a **human-approved proposal** ([delegated authority](./trust-model.md#delegated-authority)) |
| `model` | Optional model override |

**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**](./deploy.md) — host your page on your own branded origin.
- [**Verify it**](./verify.md) — confirm the deployed Space is exactly what it claims.
- **Reference:** [Platform API (OpenAPI)](./api-reference.md) · [The SDK](./sdk.md).