pcli/openspec/changes/archive/2026-02-11-replace-auth-with-api-key/design.md

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.