3.4 KiB
Keytracker Backend
This is the keytracker backend. It provides a stateless HTTP API for the Website and the Telegram Bot.
Installation & Configuration
The backend is written in Python based on Flask.
See here for installation instructions.
For development purpuses you can start the server with python3 server.py, however for production
you should use a instead (Flask Deployment).
The configuration is in config. An example configuration is provided in example-config. Start of by
copying the example config: cp example-config config and edit to your needs.
Adding a key
The keys are configured in the config file in the Keys section. There is one line for each key.
You can use the script generate_key.py to generate the configuration line.
Please note that (as of now) not all changes are automatically synced to the database.
Adding a key is no problem, however (as of now, this is a TODO) deleting a key is not yet supported:
The token and history remain in the database and can still be used, however it is no longer possible
to retrieve the key name and get a new auth token to query the keyholder.
Changing the key name does also automatically update as the key name is not stored in the database.
The same applies for the password. Note that when the password is changed all users that already
have access to the keyholder data keep their access (The auth token remain valid).
Changing the key id is equivalent to adding a new key and deleting the old key.
Changing the claim token will automatically add the new token to the database, however the old token
will not automatically be invalidated. To invalidate the old key (e.g. to invalidate a QR code),
you can simply delete the old claim token from the database.
API Documentation
You can use the API by GET and POST requests to your-api-url.com/<target>.
All requests are stateless, that means there are no sessions. Authentication is implemented with the
X-Auth-Token HTTP header which you need to provide on every request.
/auth (POST)
Request an auth token to query the keyholder. You need to provide that password in the pass POST data.
Note that you must also provide an already valid token (usually the claim token).
/claim (POST)
Claim a key (which key is automatically determined by your token). The POST data must contain the name
and contact as string with a length of at least two characters. This request returns a claim id.
You can use it to find out whether you are still the current keyholder.
/keyholder (GET)
Return up to 3 of the latest keyholder as JSON list (first element is the current keyholder):
[{"name": "<Name>", "contact": "<Contact>", "timestamp": <unix timestamp>}, ...].
If the auth token is not allowed to query the keyholder a 403 error is returned.
/status/<claim id> (GET)
Query whether the given claim is still the latest. This is the only request that does not require a token.
It may return the following values:
unknown - the claim id is unknown
latest - the claim is the latest claim for the associated key
outdated - the claim is no longer the latest for the associated key
/keyname (GET)
Retrieve the name of the key associated to the used token. If the key is unknown or the token is
invalid the response is empty.