Create the concept of API keys to allow third party clients to skip the CAPTCHA check on spot submission

This commit is contained in:
Ian Renton
2026-09-27 16:12:48 +01:00
parent d79c89c74a
commit 5d8cd38351
14 changed files with 155 additions and 42 deletions
+19
View File
@@ -47,6 +47,25 @@
all means base your own project on data from the main server if you like, but if you want any control over
reliability and downtime, please run your own copy instead.)</p>
<h3 class="mt-4" id="submitting-spots">Submitting Spots</h3>
<p>As well as reading data, clients can submit new spots to Spothole using the "add spot" API endpoint, e.g.
<code>https://spothole.app/api/v3/spot</code>. Spots can be added to Spothole itself, and optionally sent "upstream"
to other services such as the DX cluster. Check the <code>spot_allowed</code> and
<code>spot_submit_providers</code> fields in the "options" API response to see what the server allows.</p>
<p>To stop bots and spammers abusing the spotting function, a Spothole server can be configured to protect against this,
which means you will need an <strong>API key</strong>. API keys are issued by the operator of each Spothole server,
so get in touch with the server owner and let them know what your software is and how it will use the API. Once you
have a key, send it in the <code>X-API-Key</code> header of each add spot request. For example:</p>
<pre><code>curl --request POST \
--header "Content-Type: application/json" \
--header "X-API-Key: your-api-key-here" \
--data '{"spot":{"dx_call":"M0TRT","time":1760019539,"freq":14200000,"de_call":"M0TRT"}}' \
https://spothole.app/api/v3/spot</code></pre>
<p>Your API key identifies your software, so please keep it private. Don't commit it to a public code repository, and
don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server operator
can revoke it, and spot submission from your client will stop working. Servers that don't protect spot submission
don't need an API key, and will accept spots with or without one.</p>
<h3 class="mt-4" id="terms">Conditions of Use</h3>
<p>There are some simple, hopefully not onerous terms and conditions that you should agree to before writing a client
for the Spothole API. These probably aren't legally binding, and I'm just a random guy on the internet, I'm not