[feature]: Public API — token auth implementation + Authentication reference doc

## Summary

Ship a **first-class public REST API** for ByteChef with token-based authentication, the UI to manage tokens, and the first page of the API Reference docs (Authentication). The linked vendor doc is the **style template for the docs** only — not an integration target.

This ticket bundles three deliverables because they must land together (docs that describe non-existent endpoints are worthless, and unused endpoints without docs are invisible):

1. **Backend** — token auth infrastructure and an introspection endpoint the docs can target.
2. **Frontend** — Settings → API Keys UI to generate / list / revoke tokens.
3. **Docs** — the Authentication page, plus a locked page template for every follow-up reference page.

Follow-up tickets will document each resource (Workflows, Connections, Executions, Webhooks, Data Tables, …) using the template landed here.

---

## Deliverable 1 — Backend (token auth infrastructure)

### 1a. Personal / Workspace API tokens

- New table `api_token` (Liquibase): `id`, `user_id`, `workspace_id NULL`, `name`, `token_hash` (bcrypt/argon2 — never store plaintext), `last_used_at`, `created_at`, `revoked_at NULL`, `scope` enum (`PERSONAL` | `WORKSPACE` | `ORGANIZATION`).
- REST endpoints under `/api/platform/internal/api-tokens`:
- `POST` — create, returns plaintext token **once** (never re-fetchable).
- `GET` — list (metadata only, no token value).
- `DELETE /{id}` — revoke.
- Follow `server/libs/platform/platform-user` conventions; scope enforcement mirrors connection visibility (`PERSONAL` → self only; `WORKSPACE`/`ORG` requires `ROLE_ADMIN` — EE-gated).

### 1b. Spring Security integration

- Add a token-auth filter ahead of the existing form-login filter: if `Authorization: Bearer ` is present, resolve it against `api_token` (hash match + not revoked) and install the user's principal. On failure, return `401` without falling through to form-login.
- Update `last_used_at` asynchronously (don't block the request).
- Audit-log every `POST`/`DELETE` on `/api-tokens` via the existing `platform-audit` aspect pattern.

### 1c. Introspection endpoint

- `GET /api/platform/internal/whoami` — returns `{ userId, email, workspaces: [...], scopes: [...] }`. Permission-light (any authenticated caller), stable, no dependencies — ideal as the doc's first code sample target.

### 1d. Rate limiting decision

Either:
- **Implement** — a Bucket4j or Resilience4j limiter per token; surface `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`. Default: 600 req/min/token (matches industry median).
- **Or defer** — document "no limits currently enforced" honestly.

Decide up front (§Open questions). Don't invent numbers in the doc if the limiter isn't wired.

### 1e. Metrics

- `bytechef_api_token_create` / `_revoke` counters (tag: `scope`).
- `bytechef_api_token_auth_success` / `_failure` counters (tag: `reason` — `invalid`, `revoked`, `expired`).
- Wired via `ObjectProvider` per the repo's established pattern.

---

## Deliverable 2 — Frontend (API keys UI)

- New route `Settings → API Keys` in the account/workspace settings area.
- Table view: token `name`, `scope`, `created_at`, `last_used_at`, revoke action.
- Create dialog: name + scope selector (scope options limited by caller's permissions).
- **One-time reveal dialog** — shows the plaintext token with a copy button and a clear "this will not be shown again" warning; closes to the table view.
- GraphQL operations (follow existing patterns in `client/src/graphql/`):
- `query ApiTokens { ... }`
- `mutation CreateApiToken(...)` — returns plaintext once.
- `mutation RevokeApiToken(...)`.
- Error handling flows through the existing `useFetchInterceptor` (no per-mutation `onError`).

---

## Deliverable 3 — Docs (Authentication page + template)

Page template locked here and reused by every follow-up reference ticket:

1. One-sentence purpose.
2. Conceptual overview (1–2 paragraphs).
3. Request details — exact header names verbatim.
4. Code samples — `cURL`, `Python`, `JavaScript`, minimum.
5. Example response (pretty-printed JSON).
6. Common errors table — status / meaning / cause / fix.

**Authentication page content:**

- Methods — Bearer API token (primary); session cookie (UI-only, mentioned so integrators don't get confused by DevTools).
- Obtaining credentials — UI path from Deliverable 2 (*Settings → API Keys → New Token*).
- Key scoping — Personal / Workspace / Organization; CE only sees Personal.
- Header format:
```
Authorization: Bearer
Content-Type: application/json
```
- Base URL — `https:///api`; note self-hosted vs. cloud host variance.
- Code samples — all three languages targeting `GET /api/platform/internal/whoami` (from Deliverable 1c). Copy-paste runnable with an obvious `$BYTECHEF_TOKEN` placeholder.
- Common errors — 401 (bad/missing/whitespace token), 403 (scope mismatch), 429 (only if Deliverable 1d ships the limiter).

Also ship `docs/reference-contributing.md` — the page template + authoring rules — so follow-up tickets don't drift.

---

## Placement & tooling (docs)

Pick one before authoring:
1. **In-repo `docs/`** rendered by the current site generator (preferred if one already exists — zero new tooling).
2. **SpringDoc + Redoc overlay** at `/api-docs`.
3. **External docs vendor** (Mintlify / Readme.com) — fastest, external lock-in.

---

## Out of scope (phase 1)

- Endpoint-by-endpoint reference pages beyond Authentication — follow-up tickets.
- OAuth 2.0 / OIDC client-credentials flow for the public API — separate ticket.
- Published SDKs (Python/JS) — mentioned in docs but tracked separately.
- Token expiration / rotation automation — tokens are long-lived until revoked in phase 1.

---

## Open questions

1. **Docs tool** — does the current website already use Hugo / Astro / Docusaurus / Mintlify? Decide before authoring.
2. **Canonical docs home** — in-repo `docs/`, website repo, or a dedicated docs repo?
3. **Rate limiting** — ship the limiter in phase 1 or defer and document "none"?
4. **Token storage** — bcrypt vs. argon2id? Argon2id preferred for new work but bcrypt is already in the codebase for passwords — consistency vs. modernity.
5. **Existing token infra** — is there a pre-existing PAT/API-key model in `platform-user` we should extend, or is this net-new? Confirm before Liquibase authoring.
6. **Self-hosted vs cloud auth parity** — does the same token/header format work in both? Should, but confirm.

---