# 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
```