Core Concepts

Understanding the key concepts of Lunar Stream will help you build better integrations.

Architecture Overview

How It Works

Step	Component	Action
1	Your Backend	Call API with ls-api-key to create livestream
2	Lunar Stream	Returns streamKey, pushToken, rtmpUrl, hlsSources
3	Broadcaster	Connects to RTMP URL with pushToken
4	Lunar Stream	Processes and delivers to CDN network
5	Viewer App	Plays HLS stream from CDN URLs

Integration Flow

Integration Steps:

Phase	Your Action	Lunar Stream Response
Setup	Call POST /livestream with API Key	Returns streamKey, pushToken, rtmpUrl
Broadcast	Send RTMP URL to broadcaster app	Accepts connection, processes stream
Playback	Send HLS URLs to viewer app	Delivers video via global CDN

Stream Lifecycle

Stream States

State	Description
READY_FOR_USE	Stream created, waiting for broadcaster to connect
STARTED	Broadcaster is actively streaming
ENDED	Broadcaster disconnected, stream ended
TOKEN_EXPIRED	Push token expired, needs refresh

Authentication Flow

Authentication Tokens

API Key

Your server-to-server authentication credential:

• Purpose: Authenticate API requests from your backend
• Lifetime: Never expires (until regenerated)
• Header: ls-api-key: <your_api_key>
• Scope: All operations within your project

curl -X GET "https://api.xxxxxx.xxx/api/v1/livestream" \
  -H "ls-api-key: ls_proj_v1_aBcDeFgHiJkLmNoPqRsTuVwXyZ..."

Security

Keep your API Key secret. Never expose it in client-side code or public repositories.

Push Token

One-time use token for RTMP stream authentication:

• Purpose: Authorize broadcaster to push RTMP stream
• Lifetime: Default 1 hour (configurable via expiresIn parameter)
• Format: JWT token
• Usage: Appended to stream key as query parameter

rtmp://ingest.lunarstream.kozow.com/live/streamKey?pushToken=eyJhbGciOiJSUzI1NiIs...

Token Refresh

Generate a new push token before the current one expires to ensure uninterrupted streaming.

Stream Key

A unique identifier for each livestream:

• Format: 32-character hexadecimal string
• Example: ee04affe2a669854052102fe762bd715
• Generated: Automatically when creating a livestream
• Immutable: Cannot be changed after creation

HLS Delivery

Streams are delivered via HLS (HTTP Live Streaming) through our global CDN network:

URL Structure

https://{cdn-host}/live/{streamKey}/hls.m3u8

Multi-CDN URLs

Each stream has multiple CDN endpoints for redundancy and optimal performance:

CDN	URL Pattern	Coverage
Primary	https://stream.lunarstream.kozow.com/live/{streamKey}/hls.m3u8	Global
BunnyCDN	https://zlmediakit-cdn.b-cdn.net/live/{streamKey}/hls.m3u8	Global
Gcore	https://gcore-zlmediakit.lunarstream.kozow.com/live/{streamKey}/hls.m3u8	Global

Best Practice

Implement CDN failover in your player to automatically switch between CDN endpoints if one becomes unavailable.

Projects & Teams

Team

• Container for projects
• Has an owner (user who created it)
• Can have multiple projects

Project

• Container for livestreams
• Has a unique API Key
• Belongs to a team
• Isolates resources and billing

Next Steps

• Quick Start Guide - Create your first livestream
• API Reference - Complete API documentation
• RTMP Streaming - Configure your encoder
• HLS Playback - Integrate video player