Core concepts

AppLooma RTC has a small vocabulary. Nine terms cover almost everything you will meet in the SDKs and the REST API. Read this once and the rest of the documentation will read faster.

Project and App ID#

A project is one application on your account. It owns its own channels, its own key pairs and its own usage. Most teams keep one project for development and one for production, so test traffic never mixes with real traffic.

Each project has an App ID. It identifies the project to the SDK and is safe to ship inside your app — it grants nothing on its own. Channels in different projects are separate even when they have the same name.

API key pair#

A project has one or more key pairs. Each pair is an API key (prefix ak_) and an API secret (prefix as_). Your server sends them as the x-applooma-key and x-applooma-secret headers when it calls the REST API.

The secret is stored hashed and shown once, at creation. If you lose it, rotate the key pair in the console. See Authentication.

Channel#

A channel is the place people meet. Everyone who joins the same channel in the same project can hear and see each other, subject to their role. A channel needs no setup — it comes into existence when the first participant joins, and ends when the last one leaves.

In the REST API and the server SDKs the field is called roomName. Channel names must match [a-zA-Z0-9_-]{1,64} — letters, digits, underscore and hyphen, between 1 and 64 characters. Anything else is rejected with 400.

A channel name is not a secret. Anyone who can obtain a token for it can join it, which is why your token endpoint, not the name, is what keeps people out.

Participant and identity#

A participant is one connection to a channel. Every participant carries an identity — a string of 1 to 128 characters that you choose when you issue the token. Use your own stable user ID.

Metadata

You may attach a small JSON object as metadata when issuing a token — a display name, an avatar URL, a team colour. It must be a plain object (not an array) and under 2048 bytes serialised. Metadata is embedded in the token and broadcast to every other participant in the channel, so keep it non-sensitive.

If metadata.nameis present it is also used as the participant's display name. The service adds the project and the role to the metadata itself; those fields are server-owned and cannot be overridden by anything you pass.

Roles#

Every token carries exactly one role: host, cohost or audience. The role decides whether the participant may publish media and whether they may administer the channel. It is fixed for the life of the token — to change someone's role, issue a new token and rejoin. See Roles and permissions.

Tracks#

A track is a single stream of media from one participant: their microphone, their camera, or their screen. A participant publishes tracks and subscribesto other people's tracks.

• Publishing is what host and cohost may do; audience may not.
• Subscribing is allowed for every role, including audience.
• Data messages are allowed for every role, so an audience member can still send chat.

Session lifecycle#

A sessionis one participant's stay in one channel. It opens when they join and closes when they leave or when the channel ends. Sessions are what we meter.

  Channel "lobby"
     │
     │  host joins ────────────────────────────────► session A opens
     │     │
     │     │  cohost joins ─────────────────────────► session B opens
     │     │     │
     │     │     │   tracks published and subscribed
     │     │     │
     │     │  cohost leaves ────────────────────────► session B closes
     │     │
     │  host leaves ───────────────────────────────► session A closes
     │
     └─ no participants left → channel ends

Closed sessions are folded into your daily usage totals by a rollup job. Until that runs, a session is recorded but not yet counted.

Participant-minutes#

Usage is measured in participant-minutes: one minute of one participant's session is one participant-minute. Each session is rounded up to a whole minute on its own, then added to the day's total. A 30-minute call with four people is 120 participant-minutes, not 30. See Usage and quotas.

Terminology#

The documentation uses product terms; the API uses field names. This table maps between them.

Where to go next#