From 9ca62978cc5b2a3e5071163fca7c693ddafb0a51 Mon Sep 17 00:00:00 2001 From: Erik De Weerdt Date: Tue, 17 Nov 2026 09:27:41 +0100 Subject: [PATCH 1/3] Live: document write-only pull and one-time speech credentials Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- theolive/contribution/enhancements/speech.mdx | 20 +++++++++++++++++-- theolive/contribution/ingest-protocols.mdx | 12 +++++++++++ 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/theolive/contribution/enhancements/speech.mdx b/theolive/contribution/enhancements/speech.mdx index fb61f063fa78..05be418cb17d 100644 --- a/theolive/contribution/enhancements/speech.mdx +++ b/theolive/contribution/enhancements/speech.mdx @@ -97,8 +97,24 @@ The full schema is documented in the API reference (`SpeechEnhancement` on [crea With a speech enhancement, the stream is first routed through the captioning service. This affects how you connect your encoder: -- **`rtmp-push`** and **`srt-push`**: always push to the ingest URL returned by the API for that ingest — it differs from a regular ingest's connection details (an `srt-push` ingest with a speech enhancement, for example, returns a URL without a stream key). -- **`srt-pull`**: the captioning service pulls the ingest's `url` itself, so your source must be reachable from the captioning service. +- **`rtmp-push`** and **`srt-push`**: use the push URL and stream key returned when you add the speech enhancement, as described below. These differ from a regular ingest's connection details. +- **`srt-pull`**: the captioning service pulls the ingest's `url` itself, so your source must be reachable from the captioning service. Credentials in that source URL are [write-only](../ingest-protocols.mdx#credentials-in-pull-source-urls). + +#### Save push credentials when adding speech + +For a push ingest with a speech enhancement, the encoder's full push `url` and `streamKey` are returned **only once**: in the response to the request that adds the speech enhancement, either ingest creation or an update that adds it. That response has `credentialHidden: false`. Save these connection details securely and configure your encoder before leaving the setup flow. + +Later reads return the push URL **without the key**, set `credentialHidden: true`, and omit `streamKey`. You cannot retrieve the existing key again. + +#### Replace a lost or compromised key + +To get new push credentials for a speech-enhanced ingest: + +1. Stop all engines using the ingest. See [Starting and stopping](../../platform/starting-and-stopping.mdx). +2. Call `POST /v2/ingests/{id}/rotate-key`, replacing `{id}` with the ingest ID. +3. Save the new connection details securely and update your encoder before restarting the engines. The **old key stops working** when it is rotated. + +Rotation is only allowed while all engines using the ingest are stopped. Otherwise, the API returns HTTP `409` with the error code `not_stopped`. ## Regions diff --git a/theolive/contribution/ingest-protocols.mdx b/theolive/contribution/ingest-protocols.mdx index 679b16ac60ee..2a1f3960ff16 100644 --- a/theolive/contribution/ingest-protocols.mdx +++ b/theolive/contribution/ingest-protocols.mdx @@ -42,3 +42,15 @@ SRT is an open-source protocol designed for low latency, secure, and reliable vi In **pull mode**, you can secure the connection by including the passphrase directly in the SRT URL that you configure on your channel (e.g. `srt://encoder-host:port?passphrase=my-secret`). In **push mode**, the Dolby team configures the passphrase for you and provides an SRT URL with the passphrase included. + +## Credentials in pull source URLs + +Credentials in the source `url` of a pull ingest (`srt-pull`, `rtmp-pull` or `rtsp-pull`) are **write-only**. These include SRT passphrases and stream IDs, RTMP stream keys in the last path segment, and usernames or passwords in the URL's user info. + +Neither the API nor the dashboard returns these credentials after you submit them, **including in create and update responses**. The API returns a sanitized `url` with `credentialHidden: true`: + +- **RTMP**: the last path segment (the stream key) and query are removed. +- **SRT**: the query, including any passphrase or stream ID, is removed. +- **Other pull URLs**: user info, query and fragment are removed. + +Credentials in user info are not returned for any of these types. Keep the full source URL securely: to change the source, send the **full URL, including credentials**, again. Do not reuse the sanitized response URL as the source URL in an update. From cd2e6e83b858a77f7236d652bf602016c89595aa Mon Sep 17 00:00:00 2001 From: Erik De Weerdt Date: Tue, 17 Nov 2026 09:50:42 +0100 Subject: [PATCH 2/3] Live: clarify speech connection details and pull URL redaction Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- theolive/contribution/enhancements/speech.mdx | 23 +++++++++++-------- theolive/contribution/ingest-protocols.mdx | 13 ++++++----- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/theolive/contribution/enhancements/speech.mdx b/theolive/contribution/enhancements/speech.mdx index 05be418cb17d..931f9dcadcc6 100644 --- a/theolive/contribution/enhancements/speech.mdx +++ b/theolive/contribution/enhancements/speech.mdx @@ -97,24 +97,27 @@ The full schema is documented in the API reference (`SpeechEnhancement` on [crea With a speech enhancement, the stream is first routed through the captioning service. This affects how you connect your encoder: -- **`rtmp-push`** and **`srt-push`**: use the push URL and stream key returned when you add the speech enhancement, as described below. These differ from a regular ingest's connection details. +- **`rtmp-push`** and **`srt-push`**: use the push connection details returned when the captioning service is created or when you rotate the credentials, as described below. These differ from a regular ingest's connection details. - **`srt-pull`**: the captioning service pulls the ingest's `url` itself, so your source must be reachable from the captioning service. Credentials in that source URL are [write-only](../ingest-protocols.mdx#credentials-in-pull-source-urls). -#### Save push credentials when adding speech +#### Save push connection details -For a push ingest with a speech enhancement, the encoder's full push `url` and `streamKey` are returned **only once**: in the response to the request that adds the speech enhancement, either ingest creation or an update that adds it. That response has `credentialHidden: false`. Save these connection details securely and configure your encoder before leaving the setup flow. +The full connection details for a speech-enhanced push ingest are returned **only when the captioning service is first created or when you rotate the credentials**, with `credentialHidden: false`. Save them securely and use them to configure your encoder: -Later reads return the push URL **without the key**, set `credentialHidden: true`, and omit `streamKey`. You cannot retrieve the existing key again. +- **`rtmp-push`**: the response returns the server `url` (up to the app) and a separate `streamKey`. Later reads keep the `url` unchanged, omit `streamKey`, and set `credentialHidden: true`. +- **`srt-push`**: there is no separate stream key. The push `url` itself admits the encoder. Later reads return only its scheme and host, with no port or query, and set `credentialHidden: true`. -#### Replace a lost or compromised key +The captioning service is first created by the request that adds the speech enhancement to an ingest that has never had one, either during ingest creation or in an update. An update that changes how the encoder connects, such as changing the ingest type, does **not** return the connection details. Removing and then re-adding the speech enhancement reuses the existing captioning service and does not return them either. Call the rotation endpoint below to get new connection details in these cases, or if you lose the original details. -To get new push credentials for a speech-enhanced ingest: +#### Rotate push connection details -1. Stop all engines using the ingest. See [Starting and stopping](../../platform/starting-and-stopping.mdx). -2. Call `POST /v2/ingests/{id}/rotate-key`, replacing `{id}` with the ingest ID. -3. Save the new connection details securely and update your encoder before restarting the engines. The **old key stops working** when it is rotated. +To get new push connection details for a speech-enhanced ingest: -Rotation is only allowed while all engines using the ingest are stopped. Otherwise, the API returns HTTP `409` with the error code `not_stopped`. +1. Stop every engine using the ingest, whether as its ingest or as its backup ingest. See [Starting and stopping](../../platform/starting-and-stopping.mdx). +2. Call [`POST /v2/ingests/{id}/rotate-key`](../../api/rotate-ingest-key.api.mdx), replacing `{id}` with the ingest ID. +3. Save the new connection details from the rotation response: `url` and, for RTMP only, `streamKey`, with `credentialHidden: false`. This response is the only time the new full connection details are returned. Update your encoder before restarting the engines. The **old connection details stop working** when they are rotated. + +Rotation is only allowed while every engine using the ingest, including as a backup ingest, is stopped. Otherwise, the API returns HTTP `409` with the error code `not_stopped`, and nothing changes. ## Regions diff --git a/theolive/contribution/ingest-protocols.mdx b/theolive/contribution/ingest-protocols.mdx index 2a1f3960ff16..5a1745325506 100644 --- a/theolive/contribution/ingest-protocols.mdx +++ b/theolive/contribution/ingest-protocols.mdx @@ -39,7 +39,7 @@ SRT is an open-source protocol designed for low latency, secure, and reliable vi ### SRT passphrase -In **pull mode**, you can secure the connection by including the passphrase directly in the SRT URL that you configure on your channel (e.g. `srt://encoder-host:port?passphrase=my-secret`). +In **pull mode**, you can secure the connection by including the passphrase directly in the SRT URL that you configure on your channel (e.g. `srt://encoder-host:port?passphrase=my-secret`). The passphrase is [write-only](#credentials-in-pull-source-urls). In **push mode**, the Dolby team configures the passphrase for you and provides an SRT URL with the passphrase included. @@ -47,10 +47,11 @@ In **push mode**, the Dolby team configures the passphrase for you and provides Credentials in the source `url` of a pull ingest (`srt-pull`, `rtmp-pull` or `rtsp-pull`) are **write-only**. These include SRT passphrases and stream IDs, RTMP stream keys in the last path segment, and usernames or passwords in the URL's user info. -Neither the API nor the dashboard returns these credentials after you submit them, **including in create and update responses**. The API returns a sanitized `url` with `credentialHidden: true`: +Neither the API nor the dashboard returns these credentials after you submit them, **including in create and update responses**. The API sanitizes the `url` as follows: -- **RTMP**: the last path segment (the stream key) and query are removed. -- **SRT**: the query, including any passphrase or stream ID, is removed. -- **Other pull URLs**: user info, query and fragment are removed. +- **For all three (SRT, RTMP and RTSP)**: user info, query and fragment are removed. +- **For RTMP also**: the last path segment (the stream key) is removed. -Credentials in user info are not returned for any of these types. Keep the full source URL securely: to change the source, send the **full URL, including credentials**, again. Do not reuse the sanitized response URL as the source URL in an update. +The entire SRT query is removed, including non-secret options such as `latency` or `mode`, not just the passphrase or stream ID. When anything is removed, the response includes `credentialHidden: true`. Otherwise, the URL is returned unchanged and `credentialHidden` is absent. + +Keep the full source URL securely: to change the source, send the **full URL, including credentials**, again. Do not reuse the sanitized response URL as the source URL in an update. An update that omits `url` keeps the stored URL and its credentials. From 9d98da9678411b7f502a68eb50455f6efabb60d6 Mon Sep 17 00:00:00 2001 From: Erik De Weerdt Date: Tue, 17 Nov 2026 10:38:16 +0100 Subject: [PATCH 3/3] Live: saved speech connection details survive re-adding the enhancement Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- theolive/contribution/enhancements/speech.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/theolive/contribution/enhancements/speech.mdx b/theolive/contribution/enhancements/speech.mdx index 931f9dcadcc6..23c6ec2a262b 100644 --- a/theolive/contribution/enhancements/speech.mdx +++ b/theolive/contribution/enhancements/speech.mdx @@ -107,7 +107,7 @@ The full connection details for a speech-enhanced push ingest are returned **onl - **`rtmp-push`**: the response returns the server `url` (up to the app) and a separate `streamKey`. Later reads keep the `url` unchanged, omit `streamKey`, and set `credentialHidden: true`. - **`srt-push`**: there is no separate stream key. The push `url` itself admits the encoder. Later reads return only its scheme and host, with no port or query, and set `credentialHidden: true`. -The captioning service is first created by the request that adds the speech enhancement to an ingest that has never had one, either during ingest creation or in an update. An update that changes how the encoder connects, such as changing the ingest type, does **not** return the connection details. Removing and then re-adding the speech enhancement reuses the existing captioning service and does not return them either. Call the rotation endpoint below to get new connection details in these cases, or if you lose the original details. +The captioning service is first created by the request that adds the speech enhancement to an ingest that has never had one, either during ingest creation (including ingests created together with a channel) or in an update. An update that changes how the encoder connects, such as changing the ingest type, does **not** return the new connection details: call the rotation endpoint below to get them. Removing and then re-adding the speech enhancement reuses the existing captioning service and its connection details, so details you saved earlier keep working; the response does not return them. Call the rotation endpoint when you no longer have valid connection details. #### Rotate push connection details