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

---
summary: "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."
tags:
  - type/reference
  - tool/planka
  - project/backlog-pilot
  - domain/self-hosting
scope: global
source: ovh-prod Planka deploy, 2026-07-08
date: 2026-07-08
last_updated: 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](https://github.com/plankanban/planka/issues/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]].