Released v1

2026-02-12 10:37:19 +00:00
commit b07572fed5
77 changed files with 19518 additions and 0 deletions
@@ -0,0 +1,43 @@
+## Context
+
+pcli currently authenticates to the Planka API using two mechanisms:
+1. **Bearer token** — `Authorization: Bearer <jwt>` header on every request
+2. **OIDC mode** — Bearer token + `httpOnlyToken` cookie sent together
+
+Both rely on session-based JWTs obtained externally. The `Client` struct carries both `Token` and `HttpOnlyToken` fields, and the `Do()` method conditionally attaches the cookie. The CLI exposes `PLANKA_TOKEN`, `--token`, `PLANKA_HTTP_TOKEN`, and `--http-token`.
+
+Planka now supports user-level API keys authenticated via the `x-api-key` header. This is simpler, long-lived, and eliminates the dual-mode complexity.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Replace all authentication with a single `x-api-key` header
+- Simplify the `Client` struct and constructor
+- Rename env var to `PLANKA_API_KEY` and flag to `--api-key`
+- Remove all OIDC/httpOnlyToken support
+
+**Non-Goals:**
+- Supporting both old and new auth simultaneously (no transition period)
+- API key management (creation/rotation/deletion) via pcli
+- Any changes to API endpoint paths or request/response formats
+
+## Decisions
+
+### Decision 1: Use `x-api-key` header directly
+**Choice**: Set `x-api-key: <key>` header instead of `Authorization: Bearer <key>`.
+**Rationale**: This is the header format documented by Planka for API key auth. Using the standard Planka format ensures compatibility.
+**Alternatives considered**: Using `Authorization: Bearer <api-key>` — rejected because Planka's API key auth specifically uses the `x-api-key` header.
+
+### Decision 2: Clean break, no backward compatibility
+**Choice**: Remove `PLANKA_TOKEN` and `--token` entirely, replace with `PLANKA_API_KEY` and `--api-key`.
+**Rationale**: Supporting both old and new env vars adds complexity for no real benefit. This is a CLI tool where users control their own environment. A clean break with clear error messages is simpler.
+**Alternatives considered**: Supporting both `PLANKA_TOKEN` and `PLANKA_API_KEY` with deprecation warnings — rejected as unnecessary complexity for a CLI tool.
+
+### Decision 3: Single field on Client struct
+**Choice**: Replace `Token` + `HttpOnlyToken` fields with a single `APIKey` field.
+**Rationale**: API key auth has no secondary credential. One field, one header, one code path.
+
+## Risks / Trade-offs
+
+- **Breaking change for all users** → Mitigated by clear naming (`PLANKA_API_KEY`) and error message that tells users what's needed. Users must generate an API key in Planka before upgrading.
+- **API key shown only once at creation** → Not a pcli concern, but worth noting in README that users should store their key securely.