109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
# Micro License Server
|
||
|
||
A very small, self-hosted license server intended for lower traffic projects.
|
||
|
||
This license server has no concept of separate devices, so use only if you don't intend to restrict the amount of devices that a license key can be used on.
|
||
|
||
## Environment Setup
|
||
|
||
### 1. Clone the repository
|
||
```bash
|
||
git clone https://git.lexza.ch/Lexzach/micro-license-server.git
|
||
```
|
||
|
||
|
||
### 2. Create a new `.env` file in the cloned repository with the following contents:
|
||
```env
|
||
POSTGRESQL_PASSWORD="PG_CHANGEME"
|
||
API_KEY="API_CHANGEME"
|
||
NUM_KEY_CHUNKS=5
|
||
KEY_CHUNK_LENGTH=5
|
||
```
|
||
|
||
### 3. Replace the placeholder secrets in `.env` with secure random values using `openssl rand`:
|
||
|
||
```bash
|
||
sed -i \
|
||
-e "s/PG_CHANGEME/$(openssl rand -hex 32)/" \
|
||
-e "s/API_CHANGEME/$(openssl rand -hex 32)/" \
|
||
.env
|
||
```
|
||
|
||
You can change `NUM_KEY_CHUNKS` to adjust how many chunks a license key consists of, and `KEY_CHUNK_LENGTH` to change how many characters appear in each chunk. This only changes how *new* keys are generated, so previous keys won't become invalidated.
|
||
|
||
### 4. Run `docker-compose up -d` in the cloned repository folder to start the server.
|
||
You will then have the server exposed on port 8000, if you need a different port, change it in the docker-compose file, then run `docker-compose up -d` again.
|
||
|
||
## API Endpoints
|
||
|
||
All authenticated endpoints expect a `Bearer` token via the `Authorization` header that matches `API_KEY` from `.env`. Unless stated otherwise, responses are JSON.
|
||
|
||
| Method | Path | Auth | Description | Key Request Parameters | Response Highlights |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| `GET` | `/` | No | Returns server metadata. | – | `{"version": "Micro License Server vX.Y.Z"}` |
|
||
| `POST` | `/license` | Yes | Generates a new license key. | Query: `is_active` (bool, default `true`), `expiration_date` (ISO 8601, optional), `info` (string, optional metadata) | `license_key`, `expiration_timestamp`, `is_active`, `info` |
|
||
| `GET` | `/is_valid` | No | Validates a license key and records last usage time. | Query: `license_key` (required) | Boolean validity |
|
||
| `POST` | `/license/{license_key}/disable` | Yes | Deactivates a license key. | Path: `license_key` | `license_key`, `is_active: false` |
|
||
| `POST` | `/license/{license_key}/enable` | Yes | Reactivates a license key. | Path: `license_key` | `license_key`, `is_active: true` |
|
||
| `POST` | `/license/{license_key}/expiration` | Yes | Sets or clears a license key expiration. | Path: `license_key`; Query: `expiration_date` (ISO 8601 or omit to clear) | `license_key`, `expiration_timestamp` (nullable) |
|
||
| `GET` | `/license/export` | Yes | Exports license inventory as CSV ordered by issue time. | – | CSV with `license_key,issue_timestamp,expiration_timestamp,is_active` |
|
||
| `GET` | `/history/export` | Yes | Exports audit history as CSV. | Query: `token` (optional substring filter) | CSV with `action,timestamp` |
|
||
|
||
## Usage Examples
|
||
|
||
Set your API key once for convenience:
|
||
|
||
```bash
|
||
API_KEY=$(grep API_KEY .env | cut -d'"' -f2)
|
||
BASE_URL=http://127.0.0.1:8000
|
||
```
|
||
|
||
Create a license with optional metadata:
|
||
|
||
```bash
|
||
curl -X POST "$BASE_URL/license?info=QA+test+license" \
|
||
-H "Authorization: Bearer $API_KEY"
|
||
```
|
||
|
||
Check whether a license key is valid:
|
||
|
||
```bash
|
||
curl "$BASE_URL/is_valid?license_key=PUT-LICENSE-HERE"
|
||
```
|
||
|
||
Disable and enable a license:
|
||
|
||
```bash
|
||
curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/disable" \
|
||
-H "Authorization: Bearer $API_KEY"
|
||
|
||
curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/enable" \
|
||
-H "Authorization: Bearer $API_KEY"
|
||
```
|
||
|
||
Update (or clear) the expiration timestamp:
|
||
|
||
```bash
|
||
curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/expiration" \
|
||
-H "Authorization: Bearer $API_KEY" \
|
||
-G --data-urlencode "expiration_date=$(date -u -Idate)T23:59:59Z"
|
||
|
||
curl -X POST "$BASE_URL/license/PUT-LICENSE-HERE/expiration" \
|
||
-H "Authorization: Bearer $API_KEY"
|
||
```
|
||
|
||
Download the license inventory as CSV:
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer $API_KEY" \
|
||
"$BASE_URL/license/export" -o license_export.csv
|
||
```
|
||
|
||
Download history entries filtered by a token:
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer $API_KEY" \
|
||
"$BASE_URL/history/export?token=PUT-LICENSE-HERE" \
|
||
-o history_export.csv
|
||
```
|