# Kepeink Management API

Kepeink exposes a stable HTTPS management API at `https://manage.kepeink.hu`.
The browser console is a client of the same `/api/v1/*` endpoints.

## Recommended robot setup

1. A human signs in at `https://manage.kepeink.hu`.
2. Open **Account & activity**, then **Access tokens**.
3. Create a clearly labelled API key and copy the returned `kpm_...` value.
4. Give that key to the automated client through its secret store, never in a prompt or URL.
5. Verify access before doing work:

```sh
curl -fsS https://manage.kepeink.hu/api/v1/me \
  -H "Authorization: Bearer $KEPEINK_API_KEY" \
  -H "User-Agent: my-automation/1.0"
```

Use the HTTPS API for robots. Use browser automation only for the explicitly
human-gated actions listed below. The active API contract is `/openapi.json`.

## LLM Quickstart — minimum viable tunnel (4 commands)

Prereqs: `KEPEINK_API_KEY=kpm_…` (human creates it in the dashboard under
Account & activity → Access tokens; never invent a key prefix — `kpm_` for
management API, `kpt_` for agent tokens). Every management call is
`Authorization: Bearer $KEPEINK_API_KEY` — no cookies.

```sh
# 1. Verify the key + inspect workspace/role (must be owner/admin/member to create tunnels)
curl -fsS https://manage.kepeink.hu/api/v1/me \
  -H "Authorization: Bearer $KEPEINK_API_KEY" \
  -H "User-Agent: my-automation/1.0"

# 2. Create a proxy tunnel (target must be reachable FROM the agent host)
#    body: { target, backend_mode="proxy"|"static"|"ssh" }
#    proxy target: "http://localhost:3000" | "http://127.0.0.1:8080" | "http://<lan-host>:<port>"
#    static target: "/var/www/dist" (absolute path on agent host)
#    ssh target: "host:22"  (web terminal)
#    response { tunnel_id, sni, public_url, agent_token: "kpt_…" } — agent_token shown ONCE
curl -fsS -X POST https://manage.kepeink.hu/api/v1/tunnels \
  -H "Authorization: Bearer $KEPEINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"http://localhost:3000","backend_mode":"proxy"}'

# 3a. Host service (systemd): paste the returned kpt_… inline
curl -fsSL https://cdn.kepeink.hu/install.sh | sudo sh -s -- --token=kpt_xxxxxxxx

# 3b. Docker (same compose project as the app — target must resolve INSIDE the agent container):
#     image: registry.kepeink.hu/agent:2 (anonymous pull, multi-arch, major-pinned :2)
#     env: KEPEINK_AGENT_TOKEN=kpt_… (the ONLY required env)
#     target: http://<service-name>:<port> (e.g. http://immich-server:2283), NOT http://localhost:… inside the container
#     host service: http://host.docker.internal:<port> + extra_hosts: ["host.docker.internal:host-gateway"]
#     update: docker compose pull && docker compose up -d kepeink-agent  (image is immutable; no in-container self-update)

# 4. Verify public routing
curl -fsS https://<sni>/
```

Exact JSON shapes and error codes (403 missing feature, 409 cert_worker conflict on e2e, 429 headroom): `/openapi.json`. Full tunnel/access-gate/custom-domain/e2e options: `/llms-full.txt`. Human tutorials with compose snippets: `https://kepeink.hu/docs/run-the-agent-with-docker`, `https://kepeink.hu/docs/expose-immich-with-docker`, `https://kepeink.hu/docs/end-to-end-tls`.

## Authentication

- Browser users sign in with Google OAuth when configured, by email magic link / 6-digit email code, or by exchanging a `kpm_...` API token at `/api/auth/token-login`.
- Browser sessions use the `__Host-kepeink_session` HttpOnly, Secure, SameSite=Lax cookie.
- API clients and LLM agents should use `Authorization: Bearer kpm_...`; browser automation may use the same token with `/api/auth/token-login`.
- API keys are non-expiring machine tokens. Revoke them from the dashboard when no longer needed.
- API keys inherit the current user's workspace role at creation time. Platform admins on `admin.kepeink.hu` can mint audited `kpm_...` API tokens for active users/workspaces.

## Agent Rules

- Use `GET /api/v1/me` first to learn the active workspace, role, and capabilities.
- Do not call `POST /api/v1/free-trial/activate`; it requires human browser verification.
- `POST /api/auth/start` and `POST /api/public/takedown` are also reCAPTCHA-gated browser flows.
- Prefer idempotent reads before writes.
- Include a descriptive `User-Agent` for automated clients.
- Treat takedown, billing checkout, delete, revoke, and account deletion operations as human-approval actions.
- `Tunnel on/off is POST /api/v1/tunnels/{id}/enabled` (cheap toggle), PATCH is for config changes.
- Do not call `POST /api/v1/account/mfa/email/request`, `.../email/verify`, `.../totp/start`, `.../totp/confirm`, `.../recovery-codes/regenerate`, or `.../disable`; MFA enrollment requires a human with an authenticator app and a live inbox.

## References

- Full agent guide: `/llms-full.txt`
- OpenAPI description: `/openapi.json`
- MCP/WebMCP tool annotations: `/.well-known/mcp-tools.json`
- Dashboard: `/`
- Public abuse report portal: `/report` (`/takedown` remains a compatibility path)