kenzuya/unshackle
1
0
Fork 2
mirror of https://github.com/unshackle-dl/unshackle.git synced 2026-11-12 20:15:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Deployed 87ccd666 with MkDocs version: 1.6.1

Browse Source
This commit is contained in:
2026-11-03 18:55:03 +00:00
parent 1e6a3b2809
commit 95b991a505
8 changed files with 26 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev/rest-api/authentication/index.html
+9 -13
View File
@@ -1653,10 +1653,10 @@
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#the-health-check-is-always-open" class="md-nav__link">
<a href="#the-health-check-needs-an-api-key-too" class="md-nav__link">
<span class="md-ellipsis">
The health check is always open
The health check needs an API key too
</span>
</a>
@@ -2298,10 +2298,10 @@
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#the-health-check-is-always-open" class="md-nav__link">
<a href="#the-health-check-needs-an-api-key-too" class="md-nav__link">
<span class="md-ellipsis">
The health check is always open
The health check needs an API key too
</span>
</a>
@@ -2493,7 +2493,7 @@
<ol>
<li>Add an <code>api_secret</code> to the <code>serve</code> section of your <code>unshackle.yaml</code>.</li>
<li>Start the server with <code>unshackle serve</code>.</li>
<li>Send that secret in the <code>X-Secret-Key</code> header on every request except <code>GET /api/health</code>.</li>
<li>Send that secret in the <code>X-Secret-Key</code> header on every request, <code>GET /api/health</code> included.</li>
</ol>
<div class="language-bash highlight"><span class="filename">A minimal authenticated request</span><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>curl<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: your-secret-key-here"</span><span class="w"> </span><span class="se">\</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span>http://127.0.0.1:8786/api/services
@@ -2614,9 +2614,9 @@
<p class="admonition-title">The reference client sets it for you</p>
<p>unshackle's own <a href="../../../guide/downloading/">remote download</a> client (<code>RemoteService</code>) sends <code>X-Secret-Key</code> automatically, reading the API key from your <code>remote_services</code> config. It also sends a <code>User-Agent</code> of <code>unshackle/&lt;version&gt;</code>. You only deal with the header directly when writing your own client.</p>
</div>
<h3 id="the-health-check-is-always-open">The health check is always open<a class="headerlink" href="#the-health-check-is-always-open" title="Permanent link">&para;</a></h3>
<p>One endpoint is exempt from authentication: <code>GET /api/health</code>. It never requires an API key, so you can use it for liveness and version probes without embedding a secret in your monitoring:</p>
<div class="language-bash highlight"><span class="filename">No key needed</span><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a>curl<span class="w"> </span>http://127.0.0.1:8786/api/health
<h3 id="the-health-check-needs-an-api-key-too">The health check needs an API key too<a class="headerlink" href="#the-health-check-needs-an-api-key-too" title="Permanent link">&para;</a></h3>
<p><code>GET /api/health</code> reports the running version and commit, so it sits behind the same <code>X-Secret-Key</code> check as every other route. A monitor that probes it sends an API key; a request without one gets the usual <code>401</code> body, which still proves the server is up:</p>
<div class="language-bash highlight"><span class="filename">Liveness probe</span><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a>curl<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-Secret-Key: your-secret-key-here"</span><span class="w"> </span>http://127.0.0.1:8786/api/health
</span></code></pre></div>
<div class="language-json highlight"><span class="filename">Response</span><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="p">{</span>
</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
@@ -2792,10 +2792,6 @@ that reads <code>error_code</code> to classify a <code>429</code> must cope with
<td><code>127.0.0.1:8786</code></td>
</tr>
<tr>
<td>Exempt endpoint</td>
<td><code>GET /api/health</code></td>
</tr>
<tr>
<td>Failure status</td>
<td><code>401 Unauthorized</code>, or <code>429 Too Many Requests</code> for a key over its rate limit</td>
</tr>
@@ -2834,7 +2830,7 @@ that reads <code>error_code</code> to classify a <code>429</code> must cope with
<p>The header and config are identical between modes, but the code that enforces them differs:</p>
<ul>
<li>
<p><strong>API-only server</strong> (<code>--api-only</code>, or <code>--remote-only</code> which forces API-only). An <code>api_key_authentication</code> middleware runs on every request. It lets <code>GET /api/health</code> through unconditionally, then reads <code>X-Secret-Key</code>. An empty header returns the <em>"Secret Key is Empty."</em> body. A header that is not a configured user returns <em>"Secret Key is Invalid."</em>. In this mode the accepted-keys map holds your <code>api_secret</code> (labelled <code>api_user</code>, with no devices) plus every key under <code>serve.users</code>. A per-user key therefore authenticates here exactly as it does on the integrated server, and that user's <code>services</code> allowlist applies as usual. With <code>--no-key</code>, this middleware is not installed and the users map is empty.</p>
<p><strong>API-only server</strong> (<code>--api-only</code>, or <code>--remote-only</code> which forces API-only). An <code>api_key_authentication</code> middleware runs on every request. It reads <code>X-Secret-Key</code> on every request, <code>GET /api/health</code> included. An empty header returns the <em>"Secret Key is Empty."</em> body. A header that is not a configured user returns <em>"Secret Key is Invalid."</em>. In this mode the accepted-keys map holds your <code>api_secret</code> (labelled <code>api_user</code>, with no devices) plus every key under <code>serve.users</code>. A per-user key therefore authenticates here exactly as it does on the integrated server, and that user's <code>services</code> allowlist applies as usual. With <code>--no-key</code>, this middleware is not installed and the users map is empty.</p>
</li>
<li>
<p><strong>Integrated server</strong> (default). A <code>serve_authentication</code> middleware wraps pywidevine's authentication (and pyplayready's for <code>/playready*</code> paths), and the REST routes live in the same application, guarded by the same check. Here the accepted-keys map is your full <code>serve</code> config: <code>api_secret</code> (auto-added with access to all loaded devices) plus every entry under <code>users</code>, each with its declared <code>devices</code> / <code>playready_devices</code>.</p>