feat(backend, website): add API key authentication for collections API by fhennig · Pull Request #1218 · GenSpectrum/dashboards

fhennig · 2026-05-20T07:16:40Z

Summary

DB: new api_keys_table (UUID PK, unique FK to users_table, SHA-256 key hash, timestamps)
Backend: GET/POST/DELETE /api-keys?userId= for key management; POST /internal/api-keys/validate for proxy use; ConflictException (409) added to exception handler
Proxy: authMiddleware now checks Authorization: Bearer <key> first — validates against the backend, populates gsUserId, then falls through to the existing session cookie check if absent/invalid; unexpected validation errors are logged
Frontend: /api-keys page with a React component to view key metadata, generate a new key (shown once in a modal), and revoke it

Notes

The raw key is a 32-byte SecureRandom value hex-encoded (64 chars); only its SHA-256 digest is stored

Tests

Backend (ApiKeyControllerTest): covers all endpoints — GET/POST/DELETE /api-keys and POST /internal/api-keys/validate. Cases include: no key returns 404, generated key is 64 hex chars, second key returns 409, revoked key returns 404 on validate, lastUsedAt updates on each validation call, two users can hold independent keys.

Playwright (apiKey.spec.ts): full lifecycle test — navigates to /api-keys as an authenticated user, generates a key via the UI, captures it from the show-once modal, creates a collection via Authorization: Bearer <key>, verifies the collection is returned, revokes the key in the UI, then confirms a subsequent Bearer request returns 401.

Screenshots

Screen.Recording.2026-05-21.at.15.04.15.mov

🤖 Generated with Claude Code

vercel · 2026-05-20T07:16:46Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboards	Ready	Preview, Comment	May 26, 2026 9:27am

#1200) Implements one-key-per-user API key auth as an alternative to OAuth sessions, allowing programmatic/script access via Authorization: Bearer <key> header. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Backend: ApiKeyClient + ApiKeyControllerTest covering all CRUD endpoints and the internal validate endpoint. Frontend: Playwright e2e test for the full lifecycle — generate key via UI, create a collection with Bearer auth, verify it, revoke the key, confirm the revoked key returns 401. Also fixes ktlint issues: rename package api_key → apikey, wrap long description line in ApiKeyController; fix eslint naming-convention violations in authMiddleware and apiKey.spec.ts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds API key authentication to enable programmatic access to the collections API (without browser/OAuth session), including backend storage/validation, proxy support in the website middleware, a UI management page, and end-to-end + backend test coverage.

Changes:

Backend: introduce API key persistence + key management endpoints (/api-keys) and internal validation endpoint (/internal/api-keys/validate), including 409 handling.
Website/proxy: extend authMiddleware to accept Authorization: Bearer <key> and populate gsUserId; add /api-keys UI and /api/api-keys proxy route.
Tests: add backend controller tests and Playwright E2E coverage for full key lifecycle + using Bearer auth to create collections.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
website/tests/e2e.fixture.ts	Adds authenticated fixture for the new API keys page object.
website/tests/api-keys/ApiKeyPage.ts	New Playwright page object for `/api-keys` interactions.
website/tests/api-keys/apiKey.spec.ts	New E2E test covering generate/use/revoke API key workflow.
website/src/types/pages.ts	Adds `/api-keys` route constant.
website/src/types/ApiKey.ts	Adds Zod schemas/types for API key metadata and generated key response.
website/src/pages/api/api-keys/index.ts	Proxies API key CRUD calls to the backend.
website/src/pages/api-keys/index.astro	Adds `/api-keys` page shell + auth gating.
website/src/middleware/authMiddleware.ts	Adds Bearer API key validation flow before cookie-session auth.
website/src/components/api-keys/ApiKeyManager.tsx	New UI for viewing metadata, generating, showing-once, and revoking keys.
website/src/backendApi/backendService.ts	Adds client methods for API key GET/POST/DELETE.
backend/src/test/kotlin/org/genspectrum/dashboardsbackend/controller/ApiKeyControllerTest.kt	Backend integration tests for API key endpoints and validation behavior.
backend/src/test/kotlin/org/genspectrum/dashboardsbackend/controller/ApiKeyClient.kt	Test client helpers for API key endpoints.
backend/src/main/resources/db/migration/V1.4__add_api_keys_table.sql	Adds `api_keys_table` migration (UUID PK, per-user uniqueness, hash index).
backend/src/main/kotlin/org/genspectrum/dashboardsbackend/model/apikey/ApiKeyTable.kt	Exposed table/entity for API keys + lookup helpers.
backend/src/main/kotlin/org/genspectrum/dashboardsbackend/model/apikey/ApiKeyModel.kt	Service logic for generate/revoke/validate and hash handling.
backend/src/main/kotlin/org/genspectrum/dashboardsbackend/controller/ExceptionHandler.kt	Adds `ConflictException` → HTTP 409 mapping.
backend/src/main/kotlin/org/genspectrum/dashboardsbackend/controller/ApiKeyController.kt	New REST controller for API key CRUD and internal validation endpoint.
backend/src/main/kotlin/org/genspectrum/dashboardsbackend/api/ApiKey.kt	Adds API DTOs for metadata, generation response, and validation request/response.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Enable pgcrypto extension in migration; use BackendError instanceof check instead of structural cast for 404 handling in ApiKeyManager. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Catch the unique constraint violation (SQLState 23505) on insert so concurrent requests for the same user get a 409 instead of a 500. The pre-check remains as a fast path for the common case. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Simpler and more idiomatic than catching SQLException and checking SQLState. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…convention Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The page is singular since a user can only have one key. Also adds an "API Key" link to the user dropdown menu. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…utton Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ode in description Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…rated API key Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 20, 2026 07:17 View deployment

fhennig force-pushed the feat/api-key-auth branch from d103f69 to 9cdceb4 Compare May 20, 2026 07:20

vercel Bot deployed to Preview May 20, 2026 07:20 View deployment

vercel Bot deployed to Preview May 20, 2026 08:05 View deployment

fhennig force-pushed the feat/api-key-auth branch from 00d6037 to f3d3660 Compare May 20, 2026 08:13

vercel Bot deployed to Preview May 20, 2026 08:13 View deployment

fhennig requested a review from fengelniederhammer May 20, 2026 08:28

fhennig self-assigned this May 20, 2026

vercel Bot deployed to Preview May 20, 2026 08:40 View deployment

fhennig and others added 5 commits May 20, 2026 17:09

chore(website): sort imports in api-keys page

bcc9018

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(backend): add index on api_keys_table.key_hash for fast lookup

4e34f49

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

re-use SecureRandom

4563e22

fhennig force-pushed the feat/api-key-auth branch from 064185d to 4563e22 Compare May 20, 2026 15:10

vercel Bot deployed to Preview May 20, 2026 15:10 View deployment

fengelniederhammer requested a review from Copilot May 21, 2026 10:03

Copilot started reviewing on behalf of fengelniederhammer May 21, 2026 10:04 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

fengelniederhammer reviewed May 21, 2026

View reviewed changes

review(backend, website): address PR feedback on API key feature

13ada80

Enable pgcrypto extension in migration; use BackendError instanceof check instead of structural cast for 404 handling in ApiKeyManager. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 11:55 View deployment

vercel Bot deployed to Preview May 21, 2026 12:09 View deployment

fix(backend): use DataIntegrityViolationException in generateApiKey

4bf614a

Simpler and more idiomatic than catching SQLException and checking SQLState. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 12:37 View deployment

fix(backend): explicit UTF-8 charset in sha256

0a36949

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 12:40 View deployment

test(backend): align ApiKeyControllerTest names with GIVEN/WHEN/THEN …

52f8bea

…convention Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 12:43 View deployment

feat(website): rename api-keys page to api-key; add link from user menu

1d27386

The page is singular since a user can only have one key. Also adds an "API Key" link to the user dropdown menu. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 12:52 View deployment

feat(website): show generated API key inline with copy-to-clipboard b…

8b86266

…utton Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 12:58 View deployment

feat(website): inline copy button inside generated key display

266dade

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 21, 2026 13:04 View deployment

fhennig requested a review from fengelniederhammer May 21, 2026 13:05

fix(website): tighten generatedKey locator to avoid matching inline c…

67a52cc

…ode in description Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 26, 2026 08:03 View deployment

fengelniederhammer requested a review from Copilot May 26, 2026 08:43

Copilot started reviewing on behalf of fengelniederhammer May 26, 2026 08:43 View session

Copilot AI reviewed May 26, 2026

View reviewed changes

Comment thread website/tests/api-key/apiKey.spec.ts

Comment thread website/src/components/auth/UserDropdown.astro

fengelniederhammer reviewed May 26, 2026

View reviewed changes

Comment thread website/src/components/auth/UserDropdown.astro

Comment thread website/tests/api-key/ApiKeyPage.ts Outdated

Comment thread backend/src/main/kotlin/org/genspectrum/dashboardsbackend/model/apikey/ApiKeyModel.kt

fhennig and others added 2 commits May 26, 2026 11:26

feat(website): add API Key entry to hamburger menu

e855cbd

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

test(website): use data-testid instead of CSS class selector for gene…

64f1e50

…rated API key Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 26, 2026 09:27 View deployment

fengelniederhammer approved these changes May 27, 2026

View reviewed changes

fhennig merged commit 59c1491 into main May 27, 2026
10 checks passed

fhennig deleted the feat/api-key-auth branch May 27, 2026 06:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(backend, website): add API key authentication for collections API#1218

feat(backend, website): add API key authentication for collections API#1218
fhennig merged 16 commits into
mainfrom
feat/api-key-auth

fhennig commented May 20, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

fhennig commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes

Tests

Screenshots

Uh oh!

vercel Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fhennig commented May 20, 2026 •

edited

Loading

vercel Bot commented May 20, 2026 •

edited

Loading