Skip to content

Host Protection

mirotalk-hp

Host protection lets you secure your MiroTalk P2P instance by requiring authentication before creating or joining a room.

Configuration

Set these parameters in your .env file:

Variable Default Description
HOST_PROTECTED false Require valid credentials to initialize or join a room
HOST_USER_AUTH false Require participants to authenticate before joining
HOST_USERS — Define host users in the format: username:password:displayName:allowedRooms (comma-separated rooms, or * for all)

Example:

Bash
HOST_PROTECTED=true
HOST_USER_AUTH=false
HOST_USERS="alice:<strong-password>:Alice:*|bob:<another-strong-password>:Bob:room1,room2"

HOST_USERS format

HOST_USERS uses the same format as MiroTalk SFU. Separate users with |, fields with :, and rooms with ,.

Field Required Description
username Yes Login username
password Yes Login password (1–36 characters)
displayName No Name used in the room. Users cannot change it. If omitted, users can choose their own name
allowedRooms No Rooms this login can open or join, comma-separated. * (default) allows all rooms

If a value contains :, | or ,, use the JSON format instead:

Bash
HOST_USERS='[{"username":"alice","password":"<strong-password>","displayname":"Alice","allowed_rooms":["*"]},{"username":"bob","password":"<another-strong-password>","displayname":"Bob","allowed_rooms":["room1","room2"]}]'

Use strong credentials

Use your own unique, strong credentials. The server refuses to start with well-known defaults such as admin/admin, guest/guest or MiroTalk/P2P.

Note

If a user tries to open or join a room that is not in their allowedRooms, access is denied.

How It Works

When HOST_PROTECTED is true:

  1. The host must log in with a username and password.
  2. On success, the host's IP is saved as an authenticated IP.
  3. The host can now create rooms, join rooms, and share links.
  4. Guests can join freely while the host is active.
  5. When the host leaves the room or closes the browser, their IP is removed — preventing further unauthorized access.
  6. The host must log in again to regain access.

When HOST_USER_AUTH is also true, participants are additionally required to authenticate before joining.

Token

After authentication, a JWT token is stored in window.sessionStorage.peer_token. The default expiration is 1 hour, configurable in the .env file. Tokens can also be generated through the REST API.

Room Initialization

Bypass the login page and join a room directly with a token:

Text Only
https://YOUR-DOMAIN-NAME/join/?room=test&token=TOKEN

Participant Room Entry

With HOST_PROTECTED enabled

After the host authenticates, participants can join using the room path:

Text Only
https://YOUR-DOMAIN-NAME/join/test

Or with additional query parameters:

Text Only
https://YOUR-DOMAIN-NAME/join/?room=test&name=mirotalk&audio=0&video=0&screen=0&hide=0&notify=0

With HOST_USER_AUTH enabled

Participants are prompted to log in before accessing the room:

user-auth

To skip the login prompt, pass a valid token in the URL:

Text Only
https://YOUR-DOMAIN-NAME/join/?room=test&token=TOKEN

Or with additional participant settings:

Text Only
https://YOUR-DOMAIN-NAME/join/?room=test&name=mirotalk&audio=0&video=0&screen=0&hide=0&notify=0&token=TOKEN

Presenters

By default, the first participant to join a room becomes its presenter. Use PRESENTERS in your .env file to add more presenters:

Bash
PRESENTERS='["alice", "presenter@example.com"]'

PRESENTERS only matches identities the server can verify. It never matches the name someone types in the join form. Otherwise, anyone could type a listed name and become presenter.

Setup How to make someone presenter
No authentication PRESENTERS has no effect. The first participant to join the room becomes presenter
Host login (HOST_PROTECTED or HOST_USER_AUTH) Add the login username to PRESENTERS, not the display name. In HOST_USERS="alice:<pass>:Alice:*", the login username is alice
OIDC Add the verified email or the sub claim to PRESENTERS
JWT token Join with a token created with presenter: true (see the REST API)

Tip

To make a specific person presenter every time, use host login, OIDC or a token. In open rooms without login, the first participant to join becomes presenter.

Moderator in open rooms

To keep rooms open to everyone and still have a fixed moderator, use a presenter token. Guests join without logging in. The server checks the moderator's token before granting presenter rights.

Bash
HOST_PROTECTED=false
HOST_USER_AUTH=false
HOST_USERS="mod:<strong-password>:Moderator:*"
API_KEY_SECRET=<your-secret>
API_DISABLED='["meetings"]'

The /token endpoint is disabled by default, so remove token from API_DISABLED. Generate the token with the REST API:

Bash
curl -X POST "https://YOUR-DOMAIN-NAME/api/v1/token" \
  -H "authorization: <your-secret>" \
  -H "Content-Type: application/json" \
  -d '{"username":"mod","password":"<strong-password>","presenter":true,"expire":"8h"}'

Then the moderator joins with:

Text Only
https://YOUR-DOMAIN-NAME/join/?room=myroom&name=Moderator&token=TOKEN

Note

MiroTalk P2P has no PRESENTER_JOIN_FIRST option. The first participant to join a room always becomes presenter, so the moderator should open the room before guests join.

Warning

Keep the token link private, because anyone who has it becomes presenter until the token expires. If the moderator is already in the room as a guest, they must leave and rejoin with the token link.