Roomvu MLS Hub — client portal guide

The client portal (https://mlshub.roomvu.com/portal) is where your team sees its own API client: the feeds it is granted, its usage, a browser of your data exactly as the API returns it — and, for its Owners, its security log, its Viewers (§2a) and the few settings that are yours: the allowed IP addresses, the secret, the tokens (§2 "Roles"). Everyone manages their own password and two-factor authentication. Everything it shows is what the API gives your client, nothing more. Nothing you do in the portal affects the hub's data or anyone else.

The API itself is described in the API guide.

Contents

1. Signing in

  1. The invitation. Your hub administrator invites you and sends you a one-time link (there is no self sign-up). It works once and expires after 72 hours; if it no longer works, ask for a new one.
  2. Your password: at least 12 characters, not your e-mail address.
  3. Two-factor authentication — mandatory for an Owner, optional for a Viewer. An Owner's first sign-in, after the password, asks you to set up an authenticator app (Google Authenticator, Microsoft Authenticator, 1Password …): scan the QR code, type the 6-digit code, confirm with your password. You then get 8 recovery codes — store them somewhere safe (a password manager); each works once if you lose your phone. A Viewer is signed in by the password and may turn two-factor authentication on under Account at any time — recommended.
  4. Every next sign-in: e-mail, password, then — once two-factor authentication is on — the current 6-digit code (or a recovery code).

Good to know:

2. Roles: Viewer and Owner

Each person has one role, given when they are invited. Only the hub administrator makes someone an Owner or changes an Owner; an Owner may invite Viewers (§2a).

Viewer Owner
Overview, Feeds, Usage, Data browser, Account ✓ ✓
Security log — ✓
Allowed IPs, Secret and tokens (rotate, "may be compromised", revoke every token) — ✓
Users: invite, disable and re-enable Viewers, a new link for a Viewer (§2a) — ✓
Two-factor authentication optional mandatory

2a. Managing your Viewers (Owners)

Users (under Settings) lists your client's portal users — Owners and Viewers, their status, whether 2FA is on, their last sign-in — and how many you have against your limit ("4 / 10").

What an Owner can't do here: make anyone an Owner, or change an Owner (yourself included) — ask the hub administrator. You only ever see and manage your own client's users. Every action is in the Security log, which the hub team sees too and can undo (re-enable, disable, a new link).

3. What each page shows

Page What you see
Overview whether your client is active or revoked, how many feeds it is granted, its last successful request, errors and rate-limit hits (429) in the last 24 hours, links to the API guide, changelog and Swagger
Feeds every feed granted to you (by its code, e.g. spark-sbmls), as the HubFeed entity set describes it, with the grant's mode ("full feed on activation" or "updates only") and activation time, record counts per resource (listings also per StandardStatus), and the latest change you can receive. Counts are refreshed every few minutes
Usage your status in plain words, this month's and the last 30 days' requests and records, charts per day, gauges against your limits, errors by status, an hourly log and your latest 200 requests (§3.2). Your browsing in the portal is shown apart, in its own section: it is never part of your API figures
Data browser your listings, agents, offices, open houses and photos exactly as the API returns them to you, with filters, paging and links between records — every page one real API request, shown with the request itself (§3.1)
Security log (Owners) sign-ins and failures, lockouts, password and 2FA changes, allowed-IP changes, secret rotations, token revocations, invitations, new links, users disabled and enabled — who and when. A change made by the hub team shows as "Hub administrator". No secret, token, code or password is ever recorded
Users (Owners) your client's portal users; invite, disable and re-enable Viewers, a new link for a Viewer (§2a)
Allowed IPs, Secret and tokens (Owners), Account (everyone) your settings (below)

3.1 The data browser

Everything the browser shows is one API request made for your client — with your grants, your field exclusions and your extensions — and the request is shown above the answer, so you can repeat it in your code. What the API can't do, the browser doesn't offer.

The two tabs show the same answer:

A list's Readable tab is a table of the columns the request selects (the key first; it opens the record).

3.2 The Usage page

Viewers and Owners both see it. Its figures come from hourly and daily summaries of your requests, made every hour (a few minutes past the hour): what you did in the last minutes appears after the next update — the page says when the last one was. Times are UTC; a day is a UTC day.

4. Allowed IP addresses (Owners)

Settings → Allowed IPs. A list of addresses and ranges your servers call the API from: IPv4 or IPv6, single addresses (203.0.113.7) or CIDR ranges (198.51.100.0/24, 2001:db8::/48), one per line, at most 50.

5. Rotating the secret (Owners)

Settings → Secret and tokens.

The new secret is shown on the page until you click "I have stored it — hide it"; the hub keeps only a hash and can never show it again. Store it in your secret manager — never in code, a repository, e-mail or chat.

6. If a secret leaks

Act at once (an Owner; a Viewer tells an Owner or the hub administrator first):

  1. Settings → Secret and tokens → Secret may be compromised. The old secret stops immediately (no grace period) and every token is revoked. Your servers are refused until they use the new secret, which is shown once.
  2. Put the new secret in your secret manager and redeploy your servers.
  3. If you know where your servers call from, set Allowed IPs: a leaked secret is then useless from anywhere else.
  4. Check the Security log and Usage for requests you don't recognise, and tell your hub administrator.
  5. Remove the leaked value from wherever it leaked (repository history, ticket, log).

The same applies to a leaked portal password: change it under Account (your other sessions end), and tell your administrator if you think someone signed in.

7. Your account

Account (top right): change your password — type the new one twice (at least 12 characters, not your e-mail and not your current password) and your current password, then save. Your other sessions — in another browser or on another computer — are signed out at their next click; this one stays. The change is in the Security log. Forgot it? See §1. Also here: two-factor authentication — new recovery codes, or moving to a new phone (remove the authenticator with a code and your password, then set it up again right away). Your name and e-mail are set by your administrator.