Skip to content
mondochat

Tenants and apps

A tenant is your company. It holds your dashboard members and your apps. An app is one chat installation with its own users, settings, secrets, origins and webhooks.

Before you start

Section titled “Before you start”
  • Tell mondochat staff your company name and the email of the person who will own the account. Staff create tenants. Self sign-up is off unless the platform turns it on.
  • The dashboard is at https://dash.mondochat.io.

Steps

Section titled “Steps”

  1. Get your tenant. Staff create it with a name, a status (default test) and the owner’s email. That creates the tenant, its first app, the owner’s account and the owner membership at once, and emails the owner a notice that they have access. The notice holds no link to spend. The owner signs in to the dashboard with the normal email login, whenever they like.

    The login sends a link valid 15 minutes that works once. Opening the link spends nothing: it is spent when the person presses Sign in, so mail scanners that open links cannot use it up. A sign-in lasts 7 days and is extended on use.

  2. Add your team. An owner invites members under Members by email and picks a role. Access starts at once, with a plain notice by email, and the invitee signs in with the normal email login. Inviting an existing member changes nothing. The roles are:

    Role Sees
    owner everything, including Members
    admin moderation and the settings pages: App, Secrets, Origins, Webhooks, Alerts, Test console
    moderator the moderation screens only: Queue, Conversations, People, Bans, Calls, Usage

    The last owner cannot be removed or demoted, and the attempt answers 409.

  3. Find your app. Your tenant comes with a first app. Its id is in the dashboard URL, /apps/<app id>/..., and is the Mondochat-App-Id value of server calls. Only staff create more apps, so ask staff for a second app, for example for staging. Apps never share users.

  4. Create a server secret. Open Secrets and create one. It starts with mcs_ and is shown once, so store it in your server’s configuration. It is encrypted at rest and no later read returns it. An app has at most two active secrets, and a third answers 409. To rotate, create a new secret, deploy it, then revoke the old one. A client token signed with a revoked secret fails with 401.

  5. Allow your site’s origins. Open Origins and add every origin that shows the chat, for example https://www.example.com or https://*.example.com. The chat refuses to load inside pages from any other origin.

    • Each origin is https://host[:port] with no path. An origin with a path, or with http:// (http://localhost too), answers 422. To try the chat from your own machine, serve your page over https there, for example https://localhost:8443, and list that. The Quickstart has a copy-paste self-signed certificate and proxy; the browser must accept the certificate.
    • A wildcard entry matches exactly one extra label over https, so https://*.example.com matches https://a.example.com but not https://a.b.example.com or http://a.example.com. Prefer one wildcard per registrable domain over one entry per subdomain. A wildcard takes no port and needs two labels after *., so https://*.example.com:8443 and https://*.com answer 422. It counts as one of the 20.
    • Saving replaces the whole list.

  6. Set the app’s settings. Open App to edit the settings document in the form, or send it from your server. See the settings overview.

  7. Add a webhook endpoint under Webhooks. See Webhooks overview.

  8. Try the chat without a site. Test console opens the chat as a user and role you choose, with a token signed by the app’s newest server secret. It answers 409 until the app has a secret.

Check it works

Section titled “Check it works”
  • Secrets lists your secret, and the app id shows in the dashboard URL.
  • A page on a listed origin shows the chat, and a page on another origin shows a frame-ancestors error in the console.
  • Test console opens the chat as the user you typed.

When it fails

Section titled “When it fails”
Symptom Cause
A third secret answers 409 The app already has two active secrets. Revoke one first.
Saving origins answers 422 An origin has a path or is not https, the list is over 20 entries, or the origins together take more than 1024 bytes.
A page on a listed origin shows no chat The origin does not match exactly: scheme, host and port must all match, and a wildcard covers one label only.
403 with test_user_limit A tenant in test status accepts 50 users per app. Ask staff to switch it to live.
403 forbidden at session exchange with a suspended tenant A suspended tenant cannot sign users in.
A dashboard page is missing or answers 404 Your role is below the page’s role. Admin pages need admin, and Members needs owner.
The login link answers 401 It was already used or is older than 15 minutes. Request another.

Limits

Section titled “Limits”
  • Tenant status is test, live or suspended, and only staff change it.
  • An app has at most 2 active server secrets and 20 origins, and the origins together take at most 1024 bytes.
  • A tenant in test status accepts at most 50 users per app.
  • A login link is requested at most 5 times per email per hour and 20 times per IP per hour.
Section titled “Related topics”