SecondBrain/reference/planka-v2-api-gotchas.md

summary	tags	scope	source	date	last_updated
Planka v2.1.1 API and Docker behaviors that differ from or are absent in its docs — auth/PAT limits, first-login terms flow, card-move and project-delete quirks, container uid — plus service-account credentials location for planka.hyperthrive.io.	type/reference tool/planka project/backlog-pilot domain/self-hosting	global	ovh-prod Planka deploy, 2026-07-08	2026-07-08	2026-07-08

Planka v2 API Gotchas (verified on v2.1.1)

Discovered during the ovh-prod deploy (2026-07-08), verified against a live v2.1.1 instance. Directly relevant to the backlog CLI in ~/dev/ruby-gems and any Planka automation.

1. No scoped API keys / PATs. Only POST /api/access-tokens with {emailOrUsername, password} → bearer JWT. Upstream issue #945 still open as of v2.1.1. Automation must hold real user credentials; a scoped-token proxy is the workaround.
2. First-ever login requires terms acceptance. The first POST /api/access-tokens returns E_FORBIDDEN with a pendingToken and step: "accept-terms". Flow: GET /api/terms → take item.signature → POST /api/access-tokens/accept-terms with {pendingToken, signature} → real token. Subsequent logins are normal.
3. Card move needs both fields. PATCH /api/cards/:id requires both listId and position; listId alone returns E_MISSING_OR_INVALID_PARAMS.
4. Project delete is not cascading. DELETE /api/projects/:id returns 422 "Must not have boards" — delete each board first.
5. Container uid. The ghcr.io/plankanban/planka image runs as uid 1000 (node). A bind-mounted /app/data must be chown 1000 or attachment/avatar uploads fail (container starts healthy either way — the failure is silent until first upload).

Service accounts (planka.hyperthrive.io)

Created 2026-07-08 because of gotcha #1 (no PATs — automation holds real user creds). Credentials live on the OVH server (ssh alias ovh-vps) at ~/services/planka/bot-credentials.env (mode 600); admin creds remain in ~/services/planka/.env. Copy to Bitwarden.

• planka_bot — role projectOwner; for the planka-api gem / backlog CLI / cron tick. Env vars: PLANKA_BASE_URL, PLANKA_USERNAME, PLANKA_PASSWORD.
• hermes — role boardUser (deliberately restricted; Hermes agent is less trusted). Env vars: HERMES_PLANKA_USERNAME, HERMES_PLANKA_PASSWORD.
• Usernames must match /^[a-zA-Z0-9]+((_|\.)?[a-zA-Z0-9])*$/ — no hyphens (hence planka_bot, not planka-bot).

Deploy as-built details live in the repo: ovh-prod/docs/planka-deploy-prd.md. Related: vault-backlog-pilot-plan, backlog-system-options-research.