Skip to content
Docs

Give a live channel a new stream key

POST
/v1/live/channels/{id}/rotate-key
curl --request POST \
  --url https://api.iomza.com/v1/live/channels/example/rotate-key \
  --header 'Authorization: Bearer <token>'

The old key stops working at once. Not while it is on air: stop it first. The playback URLs do not change.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Responses

Section titled “Responses”

200

Section titled “200”

The channel, with its new stream key.

Media typeapplication/json

A channel with its stream key: shown only when the channel is created or its key rotated.

object
id
required
string
object
required
string
Allowed value: live_channel
name
required
string
status
required

preparing: the channel is being set up, which can take a few minutes; its encoder is refused until then. idle: waiting for an encoder. live: streaming now. reconnecting: its encoder dropped during a stream and the stream waits up to 5 minutes for it to come back (viewers keep the DVR). stopped: refusing its encoder (see stopped_until).

string
Allowed values: preparing idle live reconnecting stopped
stopped_until
required

Until when it refuses its encoder after a stop; null with status stopped: until reactivated.

string | null
ingest
required
object
stream_key
required

The stream key: OBS’s “Stream Key”. Keep it secret: whoever has it can stream to the channel.

string
url
required

Where the encoder streams to, encrypted (RTMPS): OBS’s “Server”.

string
rtmp_url
required

The same without encryption (RTMP), for encoders that don’t support RTMPS. The stream key travels in the clear.

string
srt_url
required

Where the encoder streams to over SRT, which holds up better on unstable networks: replace {stream_key} with the stream key, it goes in this address. The stream key travels in the clear.

string
stream_key_hint
required

The stream key’s last characters, to recognize it.

string
stream_key_available
required

Whether GET …/stream-key can show the key; false for an old key: rotate it once to get one that can.

boolean
playback
required

Where a channel is played from: HLS and DASH, live at the edge or with the DVR window.

object
hls
required

HLS at the live edge (the last seconds): for players that only follow the live stream.

string
dash
required

DASH at the live edge.

string
dvr_hls
required

HLS with the DVR window, to rewind (dvr_minutes).

string
dvr_dash
required

DASH with the DVR window.

string
recording
required

Whether sessions are kept whole when they end (the playback URLs then play them from the start).

boolean
dvr_minutes
required

How far back viewers may rewind on the DVR URLs, in minutes (1–120).

number
max_duration_minutes
required

The longest session, in minutes.

number
on_air_since
required

When its session on air started; null when it isn’t on air.

string | null
ingest_allowed_ips
required

Only encoders at these IPv4 addresses or ranges may stream to it; empty: any.

Array<string>
ingest_allowed_countries
required

Only encoders in these countries may stream to it; empty: any.

Array<string>
created_at
required
string format: date-time

Example 

{
  "object": "live_channel",
  "status": "preparing"
}

401

Section titled “401”

The API key is missing, invalid or revoked.

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}

403

Section titled “403”

Valid credentials that may not do this (forbidden), your plan doesn’t include the module the route belongs to (module_not_in_plan), or your organization is suspended (organization_suspended).

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}

404

Section titled “404”

It doesn’t exist in your organization.

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}

409

Section titled “409”

Its state doesn’t allow it (a finished job, an Idempotency-Key reused with another body…).

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}

429

Section titled “429”

Too many requests: wait and retry. Answered by the gateway, so the body may differ.

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}

500

Section titled “500”

Ours: retry, and tell us if it persists.

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}

503

Section titled “503”

Momentarily unavailable: retry in a few seconds.

Media typeapplication/json
object
error
required
object
code
required

Stable: branch on it.

string
Allowed values: validation_error unauthorized quota_exceeded insufficient_balance forbidden module_not_in_plan organization_suspended not_found conflict too_many_requests internal_error service_unavailable
message
required

English, for people; may change.

string
details
required

Each problem, as path: message (validation errors).

Array<string>

Example 

{
  "error": {
    "code": "validation_error"
  }
}