Portal Management¶

A portal is an independent branded domain with its own set of subscribers, channels, and packages in the Catena system. Portals allow managing multiple IPTV services with different brands on a single infrastructure.

What is a Portal¶

A portal in Catena is an isolated space for a separate IPTV service with its own settings, subscribers, and content. Each portal represents an independent branded service with its own domain, logo, and visual design.

Key concept:

Catena Infrastructure
  ├── Portal "Netflix-like service" (myiptv.com)
  │   ├── Subscribers: 10,000
  │   ├── Channels: 200
  │   └── Branding: red logo, modern design
  ├── Portal "Regional provider" (region-tv.com)
  │   ├── Subscribers: 5,000
  │   ├── Channels: 150
  │   └── Branding: blue logo, classic style
  └── Portal "Sports service" (sport-tv.com)
      ├── Subscribers: 3,000
      ├── Channels: 50 (sports only)
      └── Branding: green logo, dynamic design

Main portal characteristics:

Independent domain — each portal accessible via its own URL
Own branding — logo, name, description, visual design
Isolated data — subscribers of one portal not visible in another
Separate content — own set of channels, packages, EPG
Branded applications — ability to create mobile app for portal
Shared infrastructure — all portals run on same servers

Why portals are needed:

Multi-branding — managing multiple IPTV brands
White-label solutions — providing service under client's brand
Geographic separation — different portals for different regions
Audience segmentation — premium and budget services on one platform
Partner projects — separate portals for B2B partners
Testing environment — separate portal for testing new features

Managing Multiple Portals¶

Multi-tenancy Concept¶

One infrastructure — multiple portals:

All portals use the same streaming servers
Content can be shared or unique to portal
One manager can control multiple portals
Billing system can serve all portals

Benefits:

Resource savings — one server for all portals
Centralized management — single admin panel
Shared content — same channels for different brands
Flexible marketing — different strategies for each portal
Scalability — easy to add new portals

One Manager — Multiple Portals¶

Scenario: IPTV business owner manages three brands

Manager: admin@company.com
  ├── Portal 1: myiptv.com (owner, full access)
  ├── Portal 2: premium-tv.com (owner, full access)
  └── Portal 3: budget-tv.com (content admin, content management)

How access works:

Manager is created separately for each portal
One email can be used across different portals
On login, system shows list of available portals
Manager selects portal to work with
API key is bound to specific portal

Manager permission types:

isAdmin — infrastructure management (creating portals, servers)
canManage — full portal management (owner)
canManageSubscribers — subscriber and subscription management
canManageContent — channels, packages, EPG management

Main Portal Parameters¶

Technical Parameters¶

Portal ID

Automatically generated when creating portal
Format: base64-encoded Snowflake ID with +/= replaced by -_.
Example: pKl9SW3AAAE.
Used in all API requests
Links all entities (subscribers, channels, packages) to portal

Internal Name (Name)

Technical portal name in system
Visible only to administrators and portal owner
Used for identification in logs and control panel
Must be unique in system
Examples: catena-netflix, my-iptv-service, test-portal

Domain

Domain name under which portal is accessible
Specified by portal owner as domain claim
Real DNS binding performed by system administrator
Used for branded mobile applications
Example: myiptv.com, tv.example.org

Owner ID

Identifier of manager — portal owner
Owner has full access to all settings
Can assign other managers
Set when creating portal

API Key

Unique key for Management API portal access
Generated automatically when creating portal
Used for authentication of all API requests
Can be regenerated via /portal/reset_api_key
Must be stored securely

Branding Parameters¶

Logo

URL or base64-encoded image of portal logo
Displayed in mobile apps and web interface
Seen by end users (subscribers)
Recommended format: PNG with transparency
Recommended size: 512x512px or higher

Title

Public portal name for end users
Displayed in applications, website, notifications
Examples: "My IPTV", "Premium TV Service", "Sport TV"

Description

Brief service description for users
Used in app stores, landing pages
Can contain slogan or brief benefits description
Example: "Best IPTV for the whole family. 200+ channels in HD quality"

Free Packages¶

Concept:

List of packages available to all portal subscribers automatically
No need to create subscription for each subscriber
Used for basic content, demo channels, trial period

Applications:

Basic channels — public, freely available channels
Trial access — first month for all new subscribers
Promo content — advertising and informational channels
Loyalty program — bonus channels for all clients

Management:

# Add package to free list
POST /portal/free-packages/{packageId}

# Remove package from free list
DELETE /portal/free-packages/{packageId}

Getting Portal Information¶

Via Web Interface¶

Log into Catena control panel
Select portal (if you have access to multiple)
Open "Portal Settings" section
View parameters:
Basic information (name, domain)
Branding (logo, description)
API key
Free packages list
Access permissions

Via Management API¶

Get current portal information:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/portal \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "portalId": "pKl9SW3AAAE.",
  "name": "my-iptv-service",
  "domain": "myiptv.com",
  "freePackages": ["basicKl9SW3AAAE.", "trialKl9SW3AAAE."],
  "branding": {
    "logo": "https://myiptv.com/logo.png",
    "title": "My IPTV Service",
    "description": "Premium IPTV streaming for everyone"
  },
  "apiKey": "secret_api_key_1234567890",
  "ownerId": "mKl9SW3AAAE.",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-10-16T14:30:00Z",
  "flags": {
    "canManage": true,
    "canManageSubscribers": true,
    "canManageContent": true
  }
}

Response fields:

portalId — unique portal identifier
name — internal technical name
domain — portal domain name
freePackages — array of free package IDs
branding — branding parameters
apiKey — API key for authentication
ownerId — portal owner ID
createdAt/updatedAt — creation and update dates
flags — current manager's access permissions

Editing a Portal¶

Via Web Interface¶

Open "Portal Settings" section
Click "Edit"
Change parameters:
User-facing title (Title)
Service description (Description)
Logo URL (Logo)
Save changes

Important: Technical parameters (name, domain, portalId) usually not editable after creation.

Via Management API¶

Update portal parameters:

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/portal \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-iptv-service",
    "branding": {
      "logo": "https://myiptv.com/new-logo.png",
      "title": "My IPTV - New Name",
      "description": "Updated service description"
    }
  }'

Response:

Updated Portal object with new values.

What can be changed:

Branding parameters (logo, title, description)
Free packages list (via separate endpoints)

What cannot be changed:

portalId — generated automatically
name — set on creation
domain — set on creation
ownerId — changed separately by administrator

API Key Management¶

API Key Security¶

API key is a secret token for portal access. Handle it carefully:

Store in secure place (environment variables, secret manager)
Don't commit to Git repositories
Don't share with third parties
Regularly update (every 6-12 months)
Update immediately if compromise suspected

API Key Regeneration¶

When to regenerate:

API key accidentally pushed to public repository
Suspected unauthorized access
Employee with key access terminated
Scheduled update per security policy
Integration or billing system change

Via Web Interface:

Open "Portal Settings"
Go to "Security" section
Click "Generate New API Key"
Confirm action
Copy new key (old one stops working immediately)
Update key in all integrations

Via Management API:

curl -X POST https://your-catena-domain.com/tv-management/api/v1/portal/reset_api_key \
  -H "X-Auth-Token: current-api-key"

Response:

{
  "portalId": "pKl9SW3AAAE.",
  "name": "my-iptv-service",
  "apiKey": "new_secret_api_key_0987654321",
  "branding": { ... },
  ...
}

Important:

Old API key stops working immediately
All current integrations with old key will start getting 401 error
Update key everywhere: billing, monitoring, scripts
Save new key in secure location

Managing Free Packages¶

Adding Free Package¶

Via Web Interface:

Open "Portal Settings"
Go to "Free Packages" section
Click "Add Package"
Select package from available list
Confirm addition

All portal subscribers immediately get access to this package's channels.

Via Management API:

curl -X POST https://your-catena-domain.com/tv-management/api/v1/portal/free-packages/basicKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Response: HTTP 201 Created

Removing Free Package¶

Via Web Interface:

Open "Portal Settings"
Go to "Free Packages" section
Find package in list
Click "Remove"
Confirm removal

Subscribers without explicit subscription to this package will lose access to its channels.

Via Management API:

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/portal/free-packages/basicKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Response: HTTP 201 Created

Important:

If subscriber has explicit subscription to package, they retain access
Removing from free doesn't delete the package itself
Changes take effect immediately

Typical Use Cases¶

Scenario 1: Multiple Brands on One Platform¶

Task: Company manages three IPTV brands

Structure:

Company "IPTV Group"
├── Brand "Premium TV" (premium-tv.com)
│   ├── Target audience: premium segment
│   ├── Content: 300 HD/4K channels
│   ├── Price: from $20/month
│   └── Branding: gold logo, elegant design
│
├── Brand "Family TV" (family-tv.com)
│   ├── Target audience: families with kids
│   ├── Content: 150 channels (movies, kids, general)
│   ├── Price: from $10/month
│   └── Branding: bright colors, friendly design
│
└── Brand "Sport TV" (sport-tv.com)
    ├── Target audience: sports fans
    ├── Content: 50 sports channels
    ├── Price: from $15/month
    └── Branding: dynamic, energetic style

Benefits:

One streaming server for all brands
Centralized content management
Different marketing strategies
Isolated subscriber bases
Infrastructure cost savings

Implementation:

Create 3 portals in Catena
Configure branding for each
Distribute channels across portals
Create packages with different pricing
Integrate with unified billing system
Deploy branded mobile apps

Scenario 2: White-label Solution for Partners¶

Task: Provide IPTV platform to partners under their brand

Business model:

You — infrastructure and content provider
Partners — subscriber base and brand owners
Each partner gets their own portal
Partner pays per subscriber count or fixed fee

Example structure:

Your platform: catena-platform.com

├── Partner 1: regional-provider.com
│   └── 5,000 subscribers
│
├── Partner 2: city-tv.com
│   └── 3,000 subscribers
│
└── Partner 3: corporate-tv.net
    └── 1,000 subscribers (corporate TV)

What partner gets:

Own portal with unique domain
Full control over branding
Access to your channel catalog
Branded mobile application
API for integration with their billing
Technical support from your team

What you do:

Create portal for partner
Provide access to channels
Maintain infrastructure
Update EPG
Ensure stable operation
Bill the partner

Workflow for creating partner portal:

Partner registers in your system
You create portal with their domain
Partner configures branding (logo, colors, name)
You connect channels per tariff
Partner gets API key for integration
You create branded mobile app for partner
Partner starts attracting subscribers

Scenario 3: Geographic Separation¶

Task: Provide IPTV in different countries/regions

Why separate portals needed:

Different content due to licensing restrictions
Different interface languages
Different currencies and payment methods
Local channels for each region
Compliance with local legislation

Example:

International IPTV service

├── Portal "IPTV Russia" (iptv.ru)
│   ├── Content: Russian + international channels
│   ├── Language: Russian
│   ├── Currency: rubles
│   └── 50,000 subscribers
│
├── Portal "IPTV Europe" (iptv.eu)
│   ├── Content: European channels
│   ├── Languages: English, German, French
│   ├── Currency: euros
│   └── 30,000 subscribers
│
└── Portal "IPTV USA" (iptv.com)
    ├── Content: American channels
    ├── Language: English
    ├── Currency: dollars
    └── 20,000 subscribers

Scenario 4: Testing Environment¶

Task: Safely test new features

Solution:

Create separate portal test.myiptv.com
Use for internal testing
Test new channels, packages, features
Don't affect production portals

Benefits:

Complete isolation from production data
Ability to experiment
Integration testing
Training new employees

Branded Mobile Applications¶

Branded App Concept¶

Each portal can have separate mobile application with unique brand.

What branded application includes:

Portal logo as app icon
Portal name in App Store / Google Play
Portal color scheme in interface
Unique Bundle ID / Package Name
Connection to portal API via API key

Platforms:

iOS — Swift/SwiftUI app for iPhone/iPad
Android — Kotlin/Java app
Android TV — Smart TV version
Apple TV — Apple TV version

App Creation Process¶

Typical workflow:

You provide portal parameters:
Domain name (domain)
Logo (logo)
Title (title)
Color scheme
API endpoint
Developer creates application:
Brands interface according to design
Integrates with Catena API
Configures SMS authentication
Implements player for viewing
Store publication:
Registration in Apple Developer / Google Play Console
Preparing screenshots and description
Passing moderation
Publishing application
Subscribers download:
Find your app in store
Install on device
Login via SMS
Watch channels

Important:

iOS requires Apple Developer account ($99/year)
Android requires Google Play Console ($25 one-time)
App must comply with store rules
App updates go through moderation

Shared Infrastructure for Portals¶

Shared Streaming Servers¶

All portals use same servers for content delivery:

┌─────────────────┐
│  Streaming      │
│  Server         │◄─────┐
│  (Flussonic)    │      │
└─────────────────┘      │
         ▲               │
         │               │
    ┌────┴────┬──────────┴───────┐
    │         │                  │
┌───┴───┐ ┌───┴───┐         ┌────┴────┐
│Portal1│ │Portal2│   ...   │Portal N │
└───────┘ └───────┘         └─────────┘

Benefits:

One source for channel → N portals
Traffic and CPU savings
Centralized stream management
Single monitoring point

Access control:

Streaming server checks subscriber's playback_token
Token contains portal_id information
Subscriber can only watch their portal's channels
Technically possible to provide one channel to multiple portals

Shared Channels for Multiple Portals¶

Scenario: One channel source for different brands

Example:

Source: "Discovery Channel" (rtmp://source.tv/discovery)
                    │
      ┌─────────────┼─────────────┐
      │             │             │
Portal A      Portal B       Portal C
Channel:      Channel:       Channel:
"Discovery"   "Discovery HD" "Discov"
(in "Science" (in premium    (in basic
 package)      package)       package)

How it works:

Channel added to each portal separately
Each portal has its own channelId
But source URL is same
Streaming server caches stream
All portals receive stream from cache

Benefits:

One source → multiple uses
Licensing cost savings (depends on contract)
Centralized EPG update
Single quality monitoring point

Best Practices¶

Portal Naming¶

Internal name (name):

Use understandable technical names
Examples: company-premium, partner-acme, test-portal
Avoid spaces and special characters
Keep consistency: brand-segment or client_name

Public name (title):

Use attractive marketing name
Examples: "Premium TV", "Family Television", "Sport TV+"
Consider target audience
Check name availability (trademark)

Content Organization¶

Channel distribution strategies:

Full duplication — all portals have same content
Easier to manage
Suitable for white-label without segmentation
Segmented content — different content for different portals
Premium portal: exclusive channels
Basic portal: standard set
Thematic portal: sports/movies/news only
Common base + unique content
Basic channels available everywhere
Premium channels only in expensive portals
Local channels in regional portals

Security¶

Protecting API keys:

# BAD - key in code
api_key = "secret_key_123456"

# GOOD - key in environment variable
api_key = os.getenv('CATENA_API_KEY')

# BETTER - key in secret manager
api_key = secrets_manager.get('catena_api_key')

Manager access permissions:

Grant minimum necessary permissions
Content admin doesn't need subscriber access
Support doesn't need API key access
Regularly review manager list
Remove access for terminated employees

Monitoring¶

What to track for each portal:

Number of active subscribers
Number of concurrent sessions
Popular channels
Login errors (failed SMS, invalid tokens)
API requests count and latency
Storage usage per portal

Tools:

Grafana dashboards with portal breakdown
Prometheus metrics with portal_id label
Alerts on anomalies (sudden subscriber drop)
Regular reports for portal owners

Troubleshooting¶

Possible causes:

Incorrect domain specified in application
API key expired after regeneration
Portal temporarily unavailable
SMS gateway not configured for portal

Solution:

Check domain in portal settings
Ensure API key is current
Check service status (API, SMS gateway)
Review authorization error logs
Test login from another app/browser

Channels Won't Play¶

Possible causes:

Streaming server issues
Channel not added to portal
Subscriber not subscribed to package with channel
Network issues on subscriber's side

Solution:

Check channel works on another portal
Ensure channel exists in this portal
Check subscriber's subscriptions
Review streaming server logs
Check subscriber's playback_token

API Returns 401 Unauthorized¶

Possible causes:

Invalid API key
API key was regenerated
Key passed in incorrect format
Key from different portal

Solution:

Check API key currency: GET /portal
Ensure key in header: X-Auth-Token: your-key
Verify using correct portal's key
Regenerate key if needed

Two Portals See Each Other's Subscribers¶

Problem: Data isolation between portals violated

This should not happen by system design. If it does:

Immediately contact technical support
Verify using correct API key
Check not mixing portals in code
Review API request logs

Causes (rare):

System bug (requires fix)
Incorrect integration (one key used for different portals)
Client-side caching

Portal Management¶

What is a Portal¶

Managing Multiple Portals¶

Multi-tenancy Concept¶

One Manager — Multiple Portals¶

Main Portal Parameters¶

Technical Parameters¶

Branding Parameters¶

Free Packages¶

Getting Portal Information¶

Via Web Interface¶

Via Management API¶

Editing a Portal¶

Via Web Interface¶

Via Management API¶

API Key Management¶

API Key Security¶

API Key Regeneration¶

Managing Free Packages¶

Adding Free Package¶

Removing Free Package¶

Typical Use Cases¶

Scenario 1: Multiple Brands on One Platform¶

Scenario 2: White-label Solution for Partners¶

Scenario 3: Geographic Separation¶

Scenario 4: Testing Environment¶

Branded Mobile Applications¶

Branded App Concept¶

App Creation Process¶

Shared Infrastructure for Portals¶

Shared Streaming Servers¶

Shared Channels for Multiple Portals¶

Best Practices¶

Portal Naming¶

Content Organization¶

Security¶

Monitoring¶

Troubleshooting¶

Subscribers Cannot Login¶

Channels Won't Play¶

API Returns 401 Unauthorized¶

Two Portals See Each Other's Subscribers¶

See Also¶