Deployed 7d31153 with MkDocs version: 1.6.1

2026-11-12 20:15:10 +00:00 · 2026-09-24 22:51:28 +00:00
parent 1ab97c836f
commit a4fe9e89ee
6 changed files with 68 additions and 9 deletions
@@ -2241,7 +2241,7 @@ dashboard UI that wants history must keep its own copy.</p>
 </tr>
 <tr>
 <td><code>/api/dashboard/sessions</code></td>
-<td>Every live remote session: <code>id</code>, <code>owner</code> (username or masked key), <code>creator_ip</code>, <code>service</code>, <code>title_id</code>, <code>titles</code>, <code>tracks</code>, <code>title</code> (the display name of the title the client is on: the last one it asked tracks for, else the first resolved title), <code>auth_status</code>, <code>auth_error</code>, <code>server_account</code> (the server profile lent to the remote session, else <code>null</code>), <code>client</code>, <code>actions</code>, <code>created_at</code> and <code>last_accessed</code> (ISO 8601) with <code>created_ts</code> and <code>last_accessed_ts</code> (Unix epoch, the same clock as log <code>ts</code>), <code>age_seconds</code>, <code>idle_seconds</code>, <code>log_seq</code>. <code>client</code> is whatever the remote client sent as <code>client</code> in its session create request. The CLI sends <code>version</code>, <code>code_hash</code> (the commit the client runs, <code>null</code> when its source cannot be read), <code>platform</code> and <code>argv</code>. <code>argv</code> is the command line the user ran: proxy and URL userinfo, secret query parameters and credential values become <code>***</code>, home and install paths shorten as in the logs, and the line is cut at 3000 characters. An older client sends less or nothing and the field is <code>{}</code>. <code>log_seq</code> is the last sequence number in the remote session's service log - poll <code>/api/dashboard/sessions/{id}/logs</code> when it changes. <code>actions</code> is the session's request log, newest last, capped at 500: <code>ts</code>, <code>method</code>, <code>action</code> (<code>titles</code>, <code>tracks</code>, <code>segments</code>, <code>license</code>, <code>prompt</code>, …), <code>query</code>, <code>status</code>, <code>ms</code>, <code>bytes_in</code>, <code>bytes_out</code>.</td>
+<td>Every live remote session: <code>id</code>, <code>owner</code> (username or masked key), <code>creator_ip</code>, <code>service</code>, <code>title_id</code>, <code>titles</code>, <code>tracks</code>, <code>title</code> (the display name of the title the client is on: the last one it asked tracks for, else the first resolved title), <code>auth_status</code>, <code>auth_error</code>, <code>server_account</code> (the server profile lent to the remote session, else <code>null</code>), <code>server_cdm</code> (<code>false</code> when the client's own device licenses the remote session), <code>server_cdm_max_height</code> (the tallest video the server CDM licenses live, else <code>null</code>), <code>client</code>, <code>actions</code>, <code>created_at</code> and <code>last_accessed</code> (ISO 8601) with <code>created_ts</code> and <code>last_accessed_ts</code> (Unix epoch, the same clock as log <code>ts</code>), <code>age_seconds</code>, <code>idle_seconds</code>, <code>log_seq</code>. <code>client</code> is whatever the remote client sent as <code>client</code> in its session create request. The CLI sends <code>version</code>, <code>code_hash</code> (the commit the client runs, <code>null</code> when its source cannot be read), <code>platform</code> and <code>argv</code>. <code>argv</code> is the command line the user ran: proxy and URL userinfo, secret query parameters and credential values become <code>***</code>, home and install paths shorten as in the logs, and the line is cut at 3000 characters. An older client sends less or nothing and the field is <code>{}</code>. <code>log_seq</code> is the last sequence number in the remote session's service log - poll <code>/api/dashboard/sessions/{id}/logs</code> when it changes. <code>actions</code> is the session's request log, newest last, capped at 500: <code>ts</code>, <code>method</code>, <code>action</code> (<code>titles</code>, <code>tracks</code>, <code>segments</code>, <code>license</code>, <code>prompt</code>, …), <code>query</code>, <code>status</code>, <code>ms</code>, <code>bytes_in</code>, <code>bytes_out</code>.</td>
 </tr>
 <tr>
 <td><code>/api/dashboard/jobs</code></td>
@@ -2342,11 +2342,11 @@ is open.</p>
 <h2 id="keys">Keys<a class="headerlink" href="#keys" title="Permanent link">&para;</a></h2>
 <div class="language-text highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>GET /api/dashboard/keys
 </span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>[{"id": "3ed054be9371", "role": "user", "label": "tier1", "services": ["EXAMPLE", "DEMO"],
-</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>  "server_cdm": false, "server_accounts": false, "server_proxy": false,
+</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>  "server_cdm": false, "server_cdm_max_height": null, "server_accounts": false, "server_proxy": false,
 </span><span id="__span-4-4"><a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>  "tier": "bot", "rate_limit": 600, "window_used": 412,
 </span><span id="__span-4-5"><a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>  "requests": 41300, "rejected": 4, "bytes_out": 103079215104, "last_seen": 1756909188.2},
 </span><span id="__span-4-6"><a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a> {"id": "7c1d0f52a884", "role": "dashboard", "label": "dash…", "services": [],
-</span><span id="__span-4-7"><a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a>  "server_cdm": false, "server_accounts": false, "server_proxy": false,
+</span><span id="__span-4-7"><a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a>  "server_cdm": false, "server_cdm_max_height": null, "server_accounts": false, "server_proxy": false,
 </span><span id="__span-4-8"><a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a>  "tier": null, "rate_limit": null, "window_used": 0,
 </span><span id="__span-4-9"><a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a>  "requests": 8140, "rejected": 0, "bytes_out": 41200311, "last_seen": 1756909350.9}]
 </span></code></pre></div>
@@ -2374,6 +2374,10 @@ here, so use <code>id</code> as the identity and <code>label</code> only for dis
 <td><code>false</code>, <code>true</code>, or the list of service tags the grant covers.</td>
 </tr>
 <tr>
+<td><code>server_cdm_max_height</code></td>
+<td>The configured limit on live server CDM licences: a height, a map of service tag to height, or <code>null</code> for no limit.</td>
+</tr>
+<tr>
 <td><code>server_proxy</code></td>
 <td>Boolean. Only a literal <code>true</code> grants it, and an API key with no <code>users</code> entry does not get it.</td>
 </tr>
@@ -4072,6 +4072,11 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
 <td><code>FORBIDDEN</code></td>
 <td>A gated parameter is not permitted.</td>
 </tr>
+<tr>
+<td><code>403</code></td>
+<td><code>SERVER_CDM_CAPPED</code></td>
+<td>The API key has a <code>server_cdm_max_height</code> for the service, and the job has no <code>quality</code> at or under it, sets <code>best_available</code>, or has <code>HYBRID</code> in <code>range</code>.</td>
+</tr>
 </tbody>
 </table>
 <h3 id="get-apidownloadjobs"><code>GET /api/download/jobs</code><a class="headerlink" href="#get-apidownloadjobs" title="Permanent link">&para;</a></h3>
@@ -4399,6 +4404,11 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
 <td><code>FORBIDDEN</code></td>
 <td>A gated parameter is no longer permitted.</td>
 </tr>
+<tr>
+<td><code>403</code></td>
+<td><code>SERVER_CDM_CAPPED</code></td>
+<td>The job is no longer inside the <code>server_cdm_max_height</code> of the API key.</td>
+</tr>
 </tbody>
 </table>
 <h3 id="post-apidownloadjobsjob_idpriority"><code>POST /api/download/jobs/{job_id}/priority</code><a class="headerlink" href="#post-apidownloadjobsjob_idpriority" title="Permanent link">&para;</a></h3>
@@ -5222,6 +5232,10 @@ A slow answer arrives as a <a href="#slow-responses">slow response</a>.</p>
 <td>403</td>
 </tr>
 <tr>
+<td><code>SERVER_CDM_CAPPED</code></td>
+<td>403</td>
+</tr>
+<tr>
 <td><code>GEOFENCE</code></td>
 <td>403</td>
 </tr>
@@ -2442,6 +2442,11 @@ but the defaults hold for the overwhelming majority of responses.</p>
 <td>The action is not allowed. Raised by server-side gates (per-key restrictions on CDM or credential overrides) and by remote session IP binding.</td>
 </tr>
 <tr>
+<td><code>SERVER_CDM_CAPPED</code></td>
+<td>403</td>
+<td>The server CDM does not license live above the <code>server_cdm_max_height</code> of the API key. <code>details.reason</code> is <code>server_cdm_max_height</code> (with <code>details.max_height</code>) or <code>client_device</code>, for a remote session where the client's own device licenses. A remote client licenses the track with its own device.</td>
+</tr>
+<tr>
 <td><code>GEOFENCE</code></td>
 <td>403</td>
 <td>The title is not available in the applicable region.</td>
@@ -2630,6 +2630,16 @@ CDM.</p>
 </div>
 </div>
 </div>
+<div class="admonition note">
+<p class="admonition-title">A height limit on the server CDM</p>
+<p>An API key with <code>server_cdm_max_height</code> gets the server CDM only up to that height. The
+session create response tells the client who licenses the session in <code>server_cdm</code> and gives
+the limit in <code>server_cdm_max_height</code>. In a server CDM session, the batch licence response
+lists each track the server refused to license live under <code>capped_tracks</code>. A single-track
+server CDM licence answers <code>403 SERVER_CDM_CAPPED</code> for such a track. In both cases the client
+licenses those tracks in proxy mode with its own local CDM. See
+<a href="../../../reference/configuration/services/"><code>server_cdm_max_height</code></a>.</p>
+</div>
 <hr />
 <h2 id="remote-session-lifecycle-and-expiry">Remote session lifecycle and expiry<a class="headerlink" href="#remote-session-lifecycle-and-expiry" title="Permanent link">&para;</a></h2>
 <p>Remote sessions live in an <strong>in-memory store on the server</strong> and expire on a timer. You
@@ -2333,6 +2333,31 @@ client configured with <code>server_cdm: true</code> to license with its own loc
 client that asks anyway gets a <code>FORBIDDEN</code> error. Because a download job always licenses with the server's CDM,
 an API key without <code>server_cdm</code> for that service also cannot submit or retry <code>/api/download</code>
 jobs. Keys that have no <code>users</code> entry, such as <code>api_secret</code>, keep server CDM access.</p>
+<p><code>server_cdm_max_height</code> limits the live licences the server's device makes for that API key.
+Set it to a height in pixels for every service, or to a map of service tag to height with an
+optional <code>default</code> entry. A service the map does not name or sets to <code>null</code> gets the <code>default</code>, and
+with no <code>default</code> it has no limit. The server compares the limit with the lowest <code>-q</code> that selects
+the track: the track height, or the 16:9 height from the width when that is lower. The server reads
+the remote client's <code>-q</code> when the remote session starts:</p>
+<ul>
+<li>With no <code>-q</code>, or a <code>-q</code> at or below the limit, the server CDM licenses the remote session. The server
+  refuses a live licence for a video track taller than the limit, and the client licenses that
+  track with its own local CDM.</li>
+<li>With a <code>-q</code> above the limit, the client's own local CDM licenses every track of the remote session.
+  The service sees the DRM system and security level of the client's device. A client with no
+  local CDM gets a <code>SERVER_CDM_CAPPED</code> error.</li>
+<li>A download job must pass a <code>quality</code> at or below the limit, and must not set <code>best_available</code> or
+  a <code>HYBRID</code> range. <code>HYBRID</code> always keeps the lowest Dolby Vision track, at any quality. A job with
+  no <code>quality</code>, with a higher one, with <code>best_available</code>, or with <code>HYBRID</code> gets a <code>SERVER_CDM_CAPPED</code>
+  error. The server checks the values the job runs with, after it applies the service defaults
+  and the <code>serve:</code> download defaults.</li>
+</ul>
+<p>The limit protects the server's device, not the content keys. For a Widevine track, a server vault
+still supplies a content key at every height. A PlayReady track never reads the vault, so above
+the limit it always goes to the client's device. A licence for a lower track can carry the
+content key of a higher track when the service shares one content key between them. With server
+accounts enabled, a client that reports a stronger device than it holds makes the server's
+account request those manifests; the licence server still refuses its challenge.</p>
 <p><code>admin</code> is a boolean that lets the API key run the maintenance endpoints (clear-cache, clear-temp, refresh-services). It is <code>false</code> unless the entry sets it. Keys that have no <code>users</code> entry, such as <code>api_secret</code>, keep that access.</p>
 <p>A <code>tier</code> names an entry under <code>serve.tiers</code>, which holds the settings that several API keys
 share. Today a tier carries <code>rate_limit</code>, the requests per hour that API key may make; an API
@@ -2410,11 +2435,12 @@ region; a client that reports none is not blocked.</p>
 </span><span id="__span-3-14"><a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a><span class="w">      </span><span class="nt">tier</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bot</span><span class="w">                   </span><span class="c1"># 600 requests/hour; 429 with Retry-After once over</span>
 </span><span id="__span-3-15"><a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a><span class="w">    </span><span class="nt">e5f6a7b8</span><span class="p">:</span>
 </span><span id="__span-3-16"><a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a><span class="w">      </span><span class="nt">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">            </span><span class="c1"># this key may have the server do the licensing</span>
-</span><span id="__span-3-17"><a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a><span class="w">    </span><span class="nt">c9d0e1f2</span><span class="p">:</span>
-</span><span id="__span-3-18"><a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a><span class="w">      </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EXAMPLE2</span><span class="p p-Indicator">]</span>
-</span><span id="__span-3-19"><a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="w">      </span><span class="nt">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w">      </span><span class="c1"># the server licenses only EXAMPLE1; EXAMPLE2 needs a local CDM</span>
-</span><span id="__span-3-20"><a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a><span class="w">      </span><span class="nt">server_accounts</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># may authenticate EXAMPLE1 with one of the server's own accounts</span>
-</span><span id="__span-3-21"><a id="__codelineno-3-21" name="__codelineno-3-21" href="#__codelineno-3-21"></a><span class="w">      </span><span class="nt">server_proxy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">          </span><span class="c1"># this key may also use the server's proxy providers</span>
+</span><span id="__span-3-17"><a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a><span class="w">      </span><span class="nt">server_cdm_max_height</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1080</span><span class="w"> </span><span class="c1"># above 1080p the client licenses with its own device</span>
+</span><span id="__span-3-18"><a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a><span class="w">    </span><span class="nt">c9d0e1f2</span><span class="p">:</span>
+</span><span id="__span-3-19"><a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="w">      </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EXAMPLE2</span><span class="p p-Indicator">]</span>
+</span><span id="__span-3-20"><a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a><span class="w">      </span><span class="nt">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w">      </span><span class="c1"># the server licenses only EXAMPLE1; EXAMPLE2 needs a local CDM</span>
+</span><span id="__span-3-21"><a id="__codelineno-3-21" name="__codelineno-3-21" href="#__codelineno-3-21"></a><span class="w">      </span><span class="nt">server_accounts</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># may authenticate EXAMPLE1 with one of the server's own accounts</span>
+</span><span id="__span-3-22"><a id="__codelineno-3-22" name="__codelineno-3-22" href="#__codelineno-3-22"></a><span class="w">      </span><span class="nt">server_proxy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">          </span><span class="c1"># this key may also use the server's proxy providers</span>
 </span></code></pre></div>
 <div class="admonition note">
 <p class="admonition-title"><code>dl</code> keys inside <code>serve</code></p>