Steve Cliff
44 lines
2.6 KiB
Markdown
44 lines
2.6 KiB
Markdown
## 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.
|