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
- 2. Roles: Viewer and Owner
- 2a. Managing your Viewers (Owners)
- 3. What each page shows
- 4. Allowed IP addresses (Owners)
- 5. Rotating the secret (Owners)
- 6. If a secret leaks
- 7. Your account
1. Signing in#
- 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.
- Your password: at least 12 characters, not your e-mail address.
- 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.
- 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:
- After 5 failed attempts (wrong password or wrong code) within 15 minutes the account is locked for 15 minutes. The message stays the same ("sign-in failed") on purpose; your administrator can unlock it.
- A session ends after 30 minutes without activity, after 12 hours in any case, and when you close the browser.
- Forgot your password? There is no "forgot password" e-mail: the hub sends no e-mail. A Viewer asks an Owner of their team (or the hub administrator); an Owner asks the hub administrator. They create a new one-time link for you (Users → "New link") and send it to you; open it, set a new password (at least 12 characters), then sign in. The link works once and expires after 72 hours; your old password keeps working until you use it, and using it signs out every session of yours. Check that whoever sends you a link is someone you know.
- Lost both your phone and your recovery codes? Ask your hub administrator: a 2FA reset clears both your password and your 2FA and gets you a new link — you set a new password, then set up 2FA again.
- Signing in to the portal is separate from the API: the portal uses your personal account; your servers use the client id and secret.
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 |
- A Viewer sees everything about the client's data and usage and changes nothing of the client; their pages do not even list the Owner pages. For a change (an address, a secret rotation), ask an Owner of your team — or your hub administrator.
- An Owner has the Owner pages only with two-factor authentication set up. Made an Owner? Your next page (or next sign-in) asks you to set up two-factor authentication first; the Owner pages appear once it is done.
- Every client keeps at least one Owner while it has Viewers. If your team's only Owner leaves, ask your administrator to make someone else Owner.
- Every role change is in the client's Security log.
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").
- Invite a Viewer: name and e-mail → the page shows a one-time invitation link once. Copy it and send it to that person through a channel you trust (not a public chat or ticket); the hub sends no e-mail. It works once and expires after 72 hours. Until it is used, the person shows as Invited.
- New link (a Viewer who forgot their password, lost the invitation or let it expire): the previous link stops working; their current password keeps working until the new link is used. Confirm the request with them first.
- Disable: the Viewer is signed out at once and can't sign in; an open link stops working. Enable lets them sign in again.
- The limit: every user who is not disabled counts, invitations not yet accepted included. At the limit, inviting (or re-enabling) is refused: disable someone who no longer needs access, or ask the hub administrator to raise it.
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.
- Resources: the tabs Property, Member, Office, OpenHouse and Media (those your client is granted).
- Filters — only on fields the API lets you filter on
(API guide §5.2), each one
comparison of the request's
$filter, and a contains box per search field (address and listing office name, agent name and e-mail, office name — the API'scontains()): listings by feed (HubFeedKey),ListingKey,ListingId,StandardStatus,PropertyType, aModificationTimestamprange (UTC), the hub's change window (HubModificationTimestamp, UTC — also on agents, offices and open houses), an agent's key (ListAgentKey,CoListAgentKey,BuyerAgentKey,CoBuyerAgentKey— one role or any) and an office's key (the four office roles); agents by feed,MemberKey,MemberMlsId,OfficeKey; offices by feed,OfficeKey,OfficeMlsId; open houses by feed,ListingKeyand anOpenHouseDaterange; photos by their parent's key (ResourceRecordKey) orMediaKey. A field your client is not served is not offered. - Pages: 10, 25 or 50 records, by key, newest
ModificationTimestampfirst, or Seek pointer — the API's seek mode (seek=true, API guide §4a): a read that stays correct while the data changes, ordered by its filter; it takes the seek filters only (a property type, an agent in any role or a "contains" box is answered with the API's own error, shown as such) — with the count ($count=true). Next follows the API's own@odata.nextLink; Previous follows again the link that led to the page before. - A record opens from the first column of a list: it is read by its
feed and key (
HubFeedKey eq … and ListingKey eq '…'— a key is unique only within a feed), with its agents, offices and photos expanded. - Links between records (the record's "Linked records"): a listing →
its list, co-list, buyer and co-buyer agents and offices, and its open
houses; an agent → its office and its listings; an office → its main
office, its agents and its listings; an open house → its listing. Each
link opens the API's own answer. A key shown without a link names a
record the API doesn't serve you (never sent by the feed, synthesized
without the
syntheticextension, or of a resource you are not granted) — nothing else about it is shown. An agent's or an office's listings are found by the key the listing carries, in the same feed. - The API request box: the method, the URL with its filter
(percent-encoded, and how it reads), the headers, Copy URL and
Copy as curl. No token is ever shown:
<your access token>/$TOKENstands for a token fromPOST /api/oauth/token(API guide §3.1). A later page's request is the next link itself. - Limits: 30 reads a minute per portal user and 120 for your whole team (each list, page or record is one read) — enough for a person clicking through, and a cap on anything automated driving the portal. Over it, the page says how long to wait. Browsing is not your API traffic: it never counts against your API rate limit, never appears in your API usage and never changes your client's last use; the Usage page shows it in its own section.
The two tabs show the same answer:
- Readable — each record laid out like a record page: its
Hub…fields first, then the RESO sections (Listing, Listing - Price, Location, … for a listing; Member, Contact, Office … for an agent), the first ones open, fields in columns, long text such asPublicRemarkson a full row, empty fields left out; Media as a list of links (no thumbnails — opening a hub-signed photo link counts as a photo download in your usage, like the API), Rooms as a table, and the extra fields (HubExtraFields) in their own section. The names are the API's field names, the values exactly the API's (onlytrue/falseread Yes/No and a list is joined by commas). It is built from the API's answer alone: nothing appears there that the JSON does not contain. - JSON — the raw response body, with a Copy button.
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.
- The status line says where you stand:
- In good standing — no request was refused for the rate limit lately; it says what share of your request and photo limits your busiest minute (see the gauges below) of the last 24 hours used.
- Close to a limit — your busiest minute of the last 24 hours reached 80 % of your request limit or of your photo limit; it says which, and how close. Spread your requests over the minute before you reach it.
- Being rate-limited — some requests were answered
429 Too Many Requeststhis hour or the last; it says how many were over the request limit and how many over the photo limit. Wait theRetry-Afterseconds before retrying. - Revoked — every request is refused; ask the hub team.
- The cards: requests and records this calendar month, and in the last 30 days with the change from the 30 days before ("new" when there was nothing to compare with).
- Records delivered per day — the records you received, stacked by
resource (Property, Member, Office, OpenHouse, Media, Lookup, HubFeed).
A listing's photos count as Media records — they arrive inside the
listing (
Mediais expanded by default) — and so do agents or offices you expand. Only successful answers count. - Requests per day — every request stacked by outcome: successful, client errors (4xx, your request was refused — the latest requests show which), rate-limited (429) and server errors (5xx, ours). Hover a bar for its numbers; "Show as a table" lists them.
- Against your limits — for this hour so far and for the last 24
hours: the peak requests in one limiter window against your
request limit, the peak photo requests in one limiter window
against your photo limit, the number of photo downloads, and the
bytes downloaded. Green is fine, amber is 80 % or more, red is at
the limit. What the rate gauges measure — exactly what the rate
limiter counts: its window opens with a request (not on the clock
minute) and lasts 60 seconds; once it holds your limit, every further
request until it ends gets
429, and the next request after it opens a new window. The gauge is the most requests one window held, so it reaches your limit exactly when requests start being refused — "40 / 40" means some were. (A burst from 10:00:40 to 10:01:30 is one window, even though it spans two clock minutes.) Bytes are the responses before compression (what travels is usually much smaller); there is no byte limit. Photos count only hub-signed photo links: a provider's own photo URL is downloaded from the provider and never seen by the hub. - Errors by status — the last 30 days' refusals by status code, with what each code means.
- Hourly log — the last 48 hours, hour by hour: requests by outcome, records, bytes, photo downloads, the peak in one limiter window, and the average and 95th-percentile response time (95 % of the requests that hour took at most that long). The current hour is counted so far.
- Latest requests — your last 200 requests as they were logged: time, method, path with its query, status, rows returned, bytes and duration. Never a token or a secret: a secret-looking query parameter is masked when the request is logged, and a photo link's signature is never logged. Requests are kept 30 days; the summaries are kept.
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.
- Empty list (the default): no restriction.
- When the list is not empty, a request from another address is
refused — the token endpoint answers
403with{"error": "access_denied"}, every API request403with the OData error codeIpNotAllowed— even with a token issued from an allowed address. - The page shows your current address as the hub sees it. Your browser and your servers usually have different addresses: list the servers'. Saving a list that does not contain your current address asks for an explicit confirmation.
- Photo links are not restricted by the list: most photo URLs are the provider's own, and the hub's signed links are already limited to one photo, your client and an expiry.
- Locked yourself out? The portal is not restricted by the list: an Owner fixes it here, or your administrator clears it.
5. Rotating the secret (Owners)#
Settings → Secret and tokens.
- Rotate the secret — routine (someone left, a yearly change). A new secret is shown once; the old one keeps working for 24 hours, so you can deploy the new one without an outage.
- Revoke every token — a bearer token leaked, the secret did not. Every current token is refused at once; your servers simply ask for a new one with the same secret.
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):
- 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.
- Put the new secret in your secret manager and redeploy your servers.
- If you know where your servers call from, set Allowed IPs: a leaked secret is then useless from anywhere else.
- Check the Security log and Usage for requests you don't recognise, and tell your hub administrator.
- 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.