Skip to main content
The Subscriber object provides secure, time-limited access control for publishing to or playing streams. It uses TOTP (Time-based One-Time Password) authentication to generate temporary access tokens.

​
Model Structure

​
subscriberId
string
required
The unique subscriber ID of the subscriber
​
subscriberName
string
The display name of the subscriber
​
streamId
string
required
The stream ID that this subscriber has access to
​
b32Secret
string
Secret code of the subscriber in Base32 format. Used for TOTP token generation. Write-only field for security
​
type
string
Type of subscriber access. Possible values:
  • play - Subscriber can only play/watch the stream
  • publish - Subscriber can publish to the stream (also includes play access for video conferencing)
​
currentConcurrentConnections
integer
default:"0"
Current count of active concurrent connections for this subscriber
​
concurrentConnectionsLimit
integer
default:"1"
Maximum number of concurrent connections allowed for this subscriber
​
blockedType
string
Type of block applied to the subscriber. Possible values: play, publish, publish_play
​
blockedUntilUnitTimeStampMs
long
default:"0"
Unix timestamp in milliseconds until which the subscriber is blocked. Value of 0 means not blocked
​
registeredNodeIp
string
The IP address of the node where subscriber is registered (for cluster environments)
​
avgVideoBitrate
long
The average video bitrate for this subscriber in bits per second
​
avgAudioBitrate
long
The average audio bitrate for this subscriber in bits per second
​
totpExpiryPeriodSeconds
integer
Custom TOTP expiry period in seconds for this subscriber. If null, falls back to global timeTokenPeriod setting

​
Authentication Flow

The Subscriber model enables time-based token authentication:
  1. Create Subscriber: Generate a subscriber with a secret (b32Secret)
  2. Generate Token: Use the secret to generate a TOTP token
  3. Access Stream: Client uses subscriberId and token to access the stream
  4. Token Validation: Server validates the token against the subscriber’s secret
  5. Access Granted: If valid and within time window, access is granted

​
Access Types

​
Play Subscriber

Subscribers with type: "play" can only watch/play the stream. This is suitable for viewer authentication. 
{
  "subscriberId": "viewer-001",
  "subscriberName": "John Doe",
  "streamId": "test-stream-123",
  "type": "play",
  "concurrentConnectionsLimit": 2
}

​
Publish Subscriber

Subscribers with type: "publish" can publish to the stream and also play it (useful for video conferencing). 
{
  "subscriberId": "publisher-001",
  "subscriberName": "Jane Smith",
  "streamId": "conference-room-1",
  "type": "publish",
  "concurrentConnectionsLimit": 1
}

​
Blocking Subscribers

You can temporarily or permanently block subscribers: 
{
  "subscriberId": "blocked-user",
  "streamId": "test-stream-123",
  "type": "play",
  "blockedType": "play",
  "blockedUntilUnitTimeStampMs": 1709625600000
}
Block types:
  • play - Block only playback access
  • publish - Block only publish access
  • publish_play - Block both publish and play access

​
Connection Limits

Control concurrent connections per subscriber: 
{
  "subscriberId": "limited-user",
  "streamId": "test-stream-123",
  "type": "play",
  "currentConcurrentConnections": 1,
  "concurrentConnectionsLimit": 3
}
When currentConcurrentConnections reaches concurrentConnectionsLimit, new connection attempts are rejected.

​
Custom TOTP Expiry

You can set a custom TOTP expiry period per subscriber: 
{
  "subscriberId": "custom-expiry-user",
  "streamId": "test-stream-123",
  "type": "play",
  "totpExpiryPeriodSeconds": 300
}
If not set, the global server setting is used.

​
Example JSON

{
  "subscriberId": "sub-12345",
  "subscriberName": "Alice Johnson",
  "streamId": "live-stream-789",
  "type": "play",
  "currentConcurrentConnections": 0,
  "concurrentConnectionsLimit": 5,
  "blockedType": null,
  "blockedUntilUnitTimeStampMs": 0,
  "registeredNodeIp": "192.168.1.10",
  "avgVideoBitrate": 2500000,
  "avgAudioBitrate": 128000,
  "totpExpiryPeriodSeconds": 60
}

​
Security Considerations

  • The b32Secret field is write-only and never returned in GET requests
  • TOTP tokens are time-limited and expire based on totpExpiryPeriodSeconds
  • Store subscriber secrets securely on the client side
  • Use HTTPS for all API requests to protect tokens in transit
  • Implement rate limiting to prevent token brute-force attacks
  • Monitor currentConcurrentConnections to detect account sharing

Build docs developers (and LLMs) love

Get started for freeTalk to us