Core Concepts

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

Stream Lifecycle

Every livestream goes through a defined lifecycle:

┌─────────────┐     Broadcaster      ┌─────────────┐
│ READY_FOR   │ ──── connects ────▶  │   STARTED   │
│    USE      │                      │             │
└─────────────┘                      └──────┬──────┘
       ▲                                    │
       │                                    │ Broadcaster
       │ Refresh token                      │ disconnects
       │                                    ▼
┌─────────────┐                      ┌─────────────┐
│   TOKEN     │ ◀── Token expires ── │   ENDED     │
│  EXPIRED    │                      │             │
└─────────────┘                      └─────────────┘

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 Tokens

API Key

• Purpose: Server-to-server authentication
• Lifetime: Never expires (until regenerated)
• Header: ls-api-key: <your_api_key>
• Scope: All operations within a project

curl -X GET "https://api.lunarstream.kozow.com/api/v1/livestream" \
  -H "ls-api-key: ls_proj_v1_aBcDeFgHiJkLmNoPqRsTuVwXyZ..."

Push Token

• Purpose: RTMP stream authentication
• Lifetime: Default 1 hour (configurable)
• Format: JWT (RS256 signed)
• Usage: Appended to stream key as query parameter

rtmp://server/live/streamKey?pushToken=eyJhbGciOiJSUzI1NiIs...

Push Token Claims:

{
  "sub": "livestream-uuid",
  "projectId": "project-uuid",
  "mediaServerId": "media-server-uuid",
  "streamKey": "32-char-hex-string",
  "iat": 1704715200,
  "exp": 1704718800,
  "type": "push_token"
}

JWT Access Token

• Purpose: User authentication (dashboard, setup)
• Lifetime: 15 minutes
• Header: Authorization: Bearer <token>
• Refresh: Use refresh token to get new access token

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):

URL Structure

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

Multi-CDN URLs

Each stream has multiple CDN endpoints for redundancy:

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

Media Servers

Lunar Stream supports multiple media server types:

Server Type	Description
ZLMediaKIT	High-performance C++ media server
MediaMTX	Lightweight Go-based media server

Choose based on your requirements:

• ZLMediaKIT: Better for high-volume, production workloads
• MediaMTX: Good for development and testing

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

• Authentication Guide - Deep dive into auth methods
• API Reference - Complete API documentation
• RTMP Streaming - Configure your encoder