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

[ivicac]

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 <token> 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<MeterRegistry> 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 <token>
  Content-Type: application/json
  

• Base URL — https://<your-instance>/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.

---