# memberapi.ose.tw backend

## Quick start

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
./scripts/start_dev.sh
```

## Required DB setup

1. Initialize API client whitelist table with `docs/API_CLIENTS_SQL.sql`.
2. Initialize core tables with `backend/scripts/init_schema.sql`.
3. Generate `api_key_hash` and update `api_clients` records, e.g.:

```bash
python scripts/generate_api_key_hash.py 'YOUR_PLAIN_KEY'
```

## Authentik JWT setup

- Configure at least one of:
  - `AUTHENTIK_JWKS_URL`
  - `AUTHENTIK_ISSUER` (the service infers `<issuer>/jwks/`)
- Optional:
  - `AUTHENTIK_AUDIENCE` (enables audience claim validation)

## Authentik Admin API setup

- Required for `/internal/authentik/users/ensure`:
  - `AUTHENTIK_BASE_URL`
  - `AUTHENTIK_ADMIN_TOKEN`
  - `AUTHENTIK_VERIFY_TLS`

## Main APIs

- `GET /healthz`
- `GET /me` (Bearer token required)
- `GET /me/permissions/snapshot` (Bearer token required)
- `POST /internal/users/upsert-by-sub`
- `GET /internal/permissions/{authentik_sub}/snapshot`
- `POST /internal/authentik/users/ensure`
- `POST /admin/permissions/grant`
- `POST /admin/permissions/revoke`