w1cdn/spothole
1
0
Fork 0
mirror of https://git.ianrenton.com/ian/spothole.git synced 2026-09-29 02:32:05 +00:00
Code Issues 13 Packages Projects Releases Wiki Activity

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

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files
static/apidocs/openapi.yml
+39 -5
View File
@@ -9,6 +9,8 @@ info:
While I provide this API for free, there are some conditions of use that you must adhere to. These are not onerous, but ensure the API can remain available to everyone. These apply even if you are getting an AI to write your client software for you. See https://spothole.app/help/usage/clients#terms for details.
If you want to submit spots from your client, an API key is required. Please contact the server owner for a key if you want to use this functionality.
## Changelog
### 3.0
@@ -24,11 +26,16 @@ info:
* **Breaking change:** In the `/options` response, `sigs` has been renamed to `activities`, and within each activity, `sig_type` has been renamed to `activity_type`.
* **Breaking change:** In the `/status` response, `sig_ref_data_providers` has been renamed to `activity_ref_data_providers`, and within each provider, `sig_name` has been renamed to `activity_name`.
* **Breaking change:** In the POST `/spot` `handling` object, `submit_upstream` and `upstream_provider` have been replaced by `upstream_providers`, a list of provider names, so a spot can be sent to multiple upstream providers at once. `upstream_credentials` is now a map of provider name to that provider's credentials.
* POST `/spot` now accepts an `X-API-Key` request header. On servers that protect spot submission, a valid API key allows a third party client to submit spots without needing to solve a CAPTCHA.
#### Upgrading a client from v2 to v3 API endpoints
In v3.0 of Spothole, the `v2` (and `v1`) API endpoints will be maintained for backwards compatibility, so if you have written a client against the `v2` API, it will continue to receive `sig`, `sig_refs` etc. as before. Where a spot or alert has more than one activity, the `v2` and `v1` APIs will return only the first one as `sig`.
If your client submits spots via POST `/spot` and uses upstream submission, replace `submit_upstream` and `upstream_provider` in the `handling` object with an `upstream_providers` list, and turn `upstream_credentials` into a map where the key is the provider name, and the value is another map of credential name to value.
Some Spothole servers, including `spothole.app`, require a CAPTCHA to submit spots via the web interface, which third-party clients can't solve. If you want your client to submit spots to such a server, ask the server operator for an API key, and send it in the `X-API-Key` request header with each add spot request.
You are encouraged to move to the `v3` API endpoints as soon as possible. To upgrade, replace `v2` with `v3` in the URLs your code calls, then rename any use of the fields, query parameters and values listed above, and handle `activities` being a list rather than a single `sig` value. If you use the activity reference lookup, call `/lookup/activityref?activity=...&id=...` instead of `/lookup/sigref?sig=...&id=...`.
### 2.2
@@ -476,9 +483,11 @@ paths:
description: >
Supply a JSON object containing a `spot` sub-object (the spot data) and an optional `handling` sub-object
containing server-side instructions such as upstream submission). Check `spot_submit_providers` in the
`/options` response to see which activities and providers support upstream submission. cURL example:
`curl --request POST --header \"Content-Type: application/json\" --data '{\"spot\":{\"dx_call\":\"M0TRT\",\"time\":1760019539,\"freq\":14200000,\"comment\":\"Test spot please ignore\",\"de_call\":\"M0TRT\"}}' https://spothole.app/api/v3/spot`"
`/options` response to see which activities and providers support upstream submission. If the server requires
an API key for spot submission, you must supply a valid API key in the `X-API-Key` header.
operationId: spot
parameters:
- $ref: '#/components/parameters/ApiKey'
requestBody:
description: Object containing a "spot" sub-object with the spot data, and an optional "handling" sub-object with server-side instructions of what to do with it.
required: true
@@ -494,6 +503,22 @@ paths:
schema:
type: string
example: "OK"
'401':
description: >
Spot submission is not allowed on this server, or the server requires an API key or CAPTCHA token and
neither was provided, or the API key was not recognised
content:
application/json:
schema:
type: string
example: "Error - API key not recognised."
'403':
description: Upstream submission was requested but this server does not allow it
content:
application/json:
schema:
type: string
example: "Error - this server does not allow upstream spot submission."
'415':
description: Incorrect Content-Type
content:
@@ -518,6 +543,14 @@ paths:
components:
parameters:
ApiKey:
name: X-API-Key
in: header
description: >
An API key issued by the server operator. On servers that protect spot submission, a valid API key allows
the spot to be submitted without a CAPTCHA token. Not required on servers that don't protect spot submission.
schema:
type: string
QrzUsername:
name: X-QRZ-Username
in: header
@@ -1410,9 +1443,10 @@ components:
captcha_token:
type: string
description: >
A Google reCAPTCHA v2 response token. Required when submitting upstream if the
server has reCAPTCHA configured. Obtain the token by completing the reCAPTCHA
widget rendered on the Add Spot page.
A Google reCAPTCHA v2 response token. Required if the server protects spot submission,
unless a valid API key is supplied in the `X-API-Key` header instead. Only useful for the
Spothole server itself, not for third-party clients, as without access to Spothole's CAPTCHA
secret they have no way of solving the CAPTCHA anyway. They must use `X-API-Key` instead.
example: "03AFY_a8Xq..."
SpotStream: