Core Concepts
The handful of ideas every MediaSFU integration uses, whether you work through an SDK or the HTTP API.
Rooms
Everything happens inside a room: meetings, calls, webinars, broadcasts, recordings and AI agents. A room has:
- a room ID (
meetingID), used to join, manage and end it; - a host (
userNameon create), unique among your active rooms; - a duration, from 5 to 1440 minutes, after which it closes;
- a capacity, the most people allowed in at once.
Create one with the Rooms API or any SDK's
create flow. The response includes the room ID, the host's secureCode, and a
publicURL that opens the room in a browser.
Room types
The eventType decides who can speak and how many people can join.
| Type | Who speaks | Up to |
|---|---|---|
conference | Everyone | 3,000 participants |
webinar | Host and panel; others watch | 3,000 participants |
broadcast | One-to-many stream | 500,000 viewers |
chat | Private one-to-one | 2 participants |
Roles
| Role | Who | What they can do |
|---|---|---|
| Host | Whoever created the room (islevel "2" in the SDKs) | Everything: admit people, moderate, record, end the room for everyone |
| Co-host | A participant the host promotes (allow it with meetingRoomParams.addCoHost) | The moderation powers the host grants |
| Participant | Everyone else (islevel "0") | What the room's settings allow: microphone, camera, screen share and chat can each be allowed, need approval, or be disallowed |
The host's secureCode proves host rights. Keep it on your server, like an API
key.
Keys and credentials
| Credential | Where it lives | Use it for |
|---|---|---|
| API username + API key | Your server only | Every HTTP call and every room create or join. Find them under API keys. |
| Disposable key | Short-lived; can be scoped and capped | Widgets and one-off integrations that shouldn't hold your main key. See the disposable keys API. |
| Room result | The client | What your server returns after it creates or joins a room for a signed-in user. It opens that one room. |
Send HTTP calls with Authorization: Bearer <api-username>:<api-key>. In apps,
the client asks your backend to create or join a room, and your backend
calls MediaSFU with the key. See Keep API keys on your backend.
Sandbox and production
Your account has separate sandbox and production usage, which the balance API reports. Use sandbox for building and testing. Disposable keys are created for one environment or the other. Production create and join requests must come from a domain on your allowed domains list when they are sent from a web app.
Room lifecycle
- Create: your server creates the room (now, or at a
scheduledDate). - Join: each person joins with the room ID; your server can also request a
join over HTTP (
action: "join"). - Leave vs end: a participant leaving affects only them. The host ending the room closes it for everyone.
- Close: the room closes when the host ends it or its duration runs out.
- After: recordings stay in MediaSFU staging for 72 hours unless you send them to your own storage.
See Leave, end and rejoin for how each SDK handles these moments.
Where to go next
- Quickstart: a live room in five minutes.
- Choose your UI mode: how much of the interface you own.
- Troubleshooting: fixes for common problems.