More information about read-only API keys in API docs.

hc/front/management/commands/pygmentize.py

@@ -47,6 +47,7 @@ class Command(BaseCommand):
         # API examples
         _process("list_checks_request", lexers.BashLexer())
         _process("list_checks_response", lexers.JsonLexer())
+        _process("list_checks_response_readonly", lexers.JsonLexer())
         _process("list_channels_request", lexers.BashLexer())
         _process("list_channels_response", lexers.JsonLexer())
         _process("create_check_request_a", lexers.BashLexer())

templates/front/docs_api.html

@@ -56,11 +56,25 @@
 
 <h2>Authentication</h2>
 <p>Your requests to {% site_name %} REST API must authenticate using an
-API key. By default, an user account on {% site_name %} doesn't have
-an API key. You can create read-write and read-only API keys
-in the <b>Project Settings</b> page.
+API key. Each project in your {% site_name %} account has separate API keys.
+There are no account-wide API keys. By default, a project on {% site_name %} doesn't have
+an API key. You can create read-write and read-only API keys in the
+<b>Project Settings</b> page.
 </p>
 
+<table class="table table-bordered">
+    <tr>
+        <td>Regular API keys</td>
+        <td>Have full access to all documented API endpoints.</td>
+    </tr>
+    <tr>
+        <td>Read-only API keys</td>
+        <td>Only work with the
+        <a href="#list-checks">Get a list of existing checks</a>
+        endpoint. Some fields are omitted from the API responses.</td>
+    </tr>
+</table>
+
 <p>The client can authenticate itself by sending an appropriate HTTP
 request header. The header's name should be <code>X-Api-Key</code> and
 its value should be your API key.
@@ -126,6 +140,13 @@ one or more tags.</p>
 <h3 class="api-section">Example Response</h3>
 {% include "front/snippets/list_checks_response.html" %}
 
+<p>When using the read-only API key, the following fields are omitted:
+   <code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>,
+   <code>channels</code>. An extra <code>unique_key</code> field is added.
+   This identifier is stable across API calls. Example:
+</p>
+{% include "front/snippets/list_checks_response_readonly.html" %}
+
 <!-- ********************************************************************** /-->
 
 <a class="section" name="create-check">

templates/front/snippets/list_checks_response_readonly.html

@@ -0,0 +1,29 @@
+<div class="highlight"><pre><span></span><span class="p">{</span>
+  <span class="nt">&quot;checks&quot;</span><span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span>
+      <span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Longer free-form description goes here&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">900</span><span class="p">,</span>
+      <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2017-01-04T13:24:39.903464+00:00&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
+      <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Api test 1&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;up&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;foo&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
+      <span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;2872190d95224bad120f41d3c06aab94b8175bb6&quot;</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+      <span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
+      <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+      <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
+      <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Api test 2&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+      <span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;0/10 * * * *&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;bar baz&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;9b5fc29129560ff2c5c1803803a7415e4f80cf7e&quot;</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>

templates/front/snippets/list_checks_response_readonly.txt

@@ -0,0 +1,28 @@
+{
+  "checks": [
+    {
+      "desc": "Longer free-form description goes here",
+      "grace": 900,
+      "last_ping": "2017-01-04T13:24:39.903464+00:00",
+      "n_pings": 1,
+      "name": "Api test 1",
+      "status": "up",
+      "tags": "foo",
+      "timeout": 3600,
+      "unique_key": "2872190d95224bad120f41d3c06aab94b8175bb6"
+    },
+    {
+      "desc": "",
+      "grace": 3600,
+      "last_ping": null,
+      "n_pings": 0,
+      "name": "Api test 2",
+      "next_ping": null,
+      "schedule": "0/10 * * * *",
+      "status": "new",
+      "tags": "bar baz",
+      "tz": "UTC",
+      "unique_key": "9b5fc29129560ff2c5c1803803a7415e4f80cf7e"
+    }
+  ]
+}