feat(gui): add API keys management routes (#23)

Implement CRUD-lite for config.api_keys with:
- List view showing all keys with usage info (which adapters reference each)
- Add form with alias validation (letters, numbers, underscores only)
- Rotate form to replace encrypted value
- Delete with protection against removing keys still referenced by adapters

Security:
- Plaintext keys never displayed back to user
- Values encrypted via crypto.encrypt() before storage
- Audit logs contain only metadata, never plaintext or encrypted values

Routes:
- GET /api-keys - list all keys
- GET /api-keys/new - add form
- POST /api-keys - create key
- GET /api-keys/{alias} - edit/rotate/delete form
- POST /api-keys/{alias} - rotate key
- POST /api-keys/{alias}/delete - delete key

Tests: 11 new tests covering list, create, rotate, delete, and audit
verification.

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

src/central/gui/audit.py

@@ -11,6 +11,9 @@ AUTH_PASSWORD_CHANGE = "auth.password_change"
 OPERATOR_CREATE = "operator.create"
 ADAPTER_UPDATE = "adapter.update"
 STREAM_UPDATE = "stream.update"
+API_KEY_CREATE = "api_key.create"
+API_KEY_ROTATE = "api_key.rotate"
+API_KEY_DELETE = "api_key.delete"
 
 
 async def write_audit(

src/central/gui/routes.py

@@ -20,6 +20,9 @@ from central.gui.auth import (
 )
 from central.gui.audit import (
     ADAPTER_UPDATE,
+    API_KEY_CREATE,
+    API_KEY_DELETE,
+    API_KEY_ROTATE,
     AUTH_LOGIN,
     AUTH_LOGIN_FAILED,
     AUTH_LOGOUT,
@@ -1104,3 +1107,421 @@ async def streams_update(
         )
 
     return RedirectResponse(url="/streams", status_code=302)
+
+
+# Alias validation regex
+ALIAS_REGEX = re.compile(r'^[a-zA-Z0-9_]+$')
+
+
+@router.get("/api-keys", response_class=HTMLResponse)
+async def api_keys_list(
+    request: Request,
+    csrf_protect: CsrfProtect = Depends(),
+) -> HTMLResponse:
+    """List all API keys."""
+    templates = _get_templates()
+    pool = get_pool()
+    operator = request.state.operator
+
+    async with pool.acquire() as conn:
+        # Fetch keys (NOT encrypted_value)
+        rows = await conn.fetch(
+            """
+            SELECT alias, created_at, rotated_at, last_used_at
+            FROM config.api_keys
+            ORDER BY alias
+            """
+        )
+
+        # For each key, find adapters that reference it
+        keys = []
+        for row in rows:
+            adapters = await conn.fetch(
+                """
+                SELECT name FROM config.adapters
+                WHERE settings->>'api_key_alias' = $1
+                ORDER BY name
+                """,
+                row["alias"],
+            )
+            keys.append({
+                "alias": row["alias"],
+                "created_at": row["created_at"],
+                "rotated_at": row["rotated_at"],
+                "last_used_at": row["last_used_at"],
+                "used_by": [a["name"] for a in adapters],
+            })
+
+    csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+    response = templates.TemplateResponse(
+        request=request,
+        name="api_keys_list.html",
+        context={
+            "operator": operator,
+            "csrf_token": csrf_token,
+            "keys": keys,
+        },
+    )
+    csrf_protect.set_csrf_cookie(signed_token, response)
+    return response
+
+
+@router.get("/api-keys/new", response_class=HTMLResponse)
+async def api_keys_new(
+    request: Request,
+    csrf_protect: CsrfProtect = Depends(),
+) -> HTMLResponse:
+    """Show form to add a new API key."""
+    templates = _get_templates()
+    operator = request.state.operator
+
+    csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+    response = templates.TemplateResponse(
+        request=request,
+        name="api_keys_new.html",
+        context={
+            "operator": operator,
+            "csrf_token": csrf_token,
+        },
+    )
+    csrf_protect.set_csrf_cookie(signed_token, response)
+    return response
+
+
+@router.post("/api-keys", response_class=HTMLResponse)
+async def api_keys_create(
+    request: Request,
+    csrf_protect: CsrfProtect = Depends(),
+) -> Response:
+    """Create a new API key."""
+    from central.crypto import encrypt
+
+    templates = _get_templates()
+    pool = get_pool()
+    operator = request.state.operator
+
+    await csrf_protect.validate_csrf(request)
+
+    form = await request.form()
+    alias = form.get("alias", "").strip()
+    plaintext_key = form.get("plaintext_key", "")
+
+    errors: dict[str, str] = {}
+
+    # Validate alias
+    if not alias:
+        errors["alias"] = "Alias is required"
+    elif len(alias) > 64:
+        errors["alias"] = "Alias must be at most 64 characters"
+    elif not ALIAS_REGEX.match(alias):
+        errors["alias"] = "Alias must contain only letters, numbers, and underscores"
+
+    # Validate plaintext_key
+    if not plaintext_key:
+        errors["plaintext_key"] = "API key is required"
+    elif len(plaintext_key) > 4096:
+        errors["plaintext_key"] = "API key must be at most 4096 characters"
+
+    if errors:
+        csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+        response = templates.TemplateResponse(
+            request=request,
+            name="api_keys_new.html",
+            context={
+                "operator": operator,
+                "csrf_token": csrf_token,
+                "errors": errors,
+                "alias": alias,
+            },
+        )
+        csrf_protect.set_csrf_cookie(signed_token, response)
+        return response
+
+    # Encrypt the key
+    encrypted_value = encrypt(plaintext_key.encode())
+
+    async with pool.acquire() as conn:
+        # Check if alias already exists
+        existing = await conn.fetchrow(
+            "SELECT alias FROM config.api_keys WHERE alias = $1",
+            alias,
+        )
+
+        if existing:
+            errors["alias"] = "An API key with this alias already exists"
+            csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+            response = templates.TemplateResponse(
+                request=request,
+                name="api_keys_new.html",
+                context={
+                    "operator": operator,
+                    "csrf_token": csrf_token,
+                    "errors": errors,
+                    "alias": alias,
+                },
+            )
+            csrf_protect.set_csrf_cookie(signed_token, response)
+            return response
+
+        # Insert the new key
+        row = await conn.fetchrow(
+            """
+            INSERT INTO config.api_keys (alias, encrypted_value)
+            VALUES ($1, $2)
+            RETURNING created_at
+            """,
+            alias,
+            encrypted_value,
+        )
+
+        # Write audit log (no plaintext!)
+        await write_audit(
+            conn,
+            API_KEY_CREATE,
+            operator_id=operator.id,
+            target=alias,
+            before=None,
+            after={"alias": alias, "created_at": row["created_at"].isoformat()},
+        )
+
+    return RedirectResponse(url="/api-keys", status_code=302)
+
+
+@router.get("/api-keys/{alias}", response_class=HTMLResponse)
+async def api_keys_edit(
+    request: Request,
+    alias: str,
+    csrf_protect: CsrfProtect = Depends(),
+) -> Response:
+    """Show form to rotate or delete an API key."""
+    templates = _get_templates()
+    pool = get_pool()
+    operator = request.state.operator
+
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            SELECT alias, created_at, rotated_at, last_used_at
+            FROM config.api_keys
+            WHERE alias = $1
+            """,
+            alias,
+        )
+
+        if row is None:
+            return Response(status_code=404, content="API key not found")
+
+        # Find adapters that reference this key
+        adapters = await conn.fetch(
+            """
+            SELECT name FROM config.adapters
+            WHERE settings->>'api_key_alias' = $1
+            ORDER BY name
+            """,
+            alias,
+        )
+
+    key = {
+        "alias": row["alias"],
+        "created_at": row["created_at"],
+        "rotated_at": row["rotated_at"],
+        "last_used_at": row["last_used_at"],
+        "used_by": [a["name"] for a in adapters],
+    }
+
+    csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+    response = templates.TemplateResponse(
+        request=request,
+        name="api_keys_edit.html",
+        context={
+            "operator": operator,
+            "csrf_token": csrf_token,
+            "key": key,
+        },
+    )
+    csrf_protect.set_csrf_cookie(signed_token, response)
+    return response
+
+
+@router.post("/api-keys/{alias}", response_class=HTMLResponse)
+async def api_keys_rotate(
+    request: Request,
+    alias: str,
+    csrf_protect: CsrfProtect = Depends(),
+) -> Response:
+    """Rotate an API key."""
+    from central.crypto import encrypt
+
+    templates = _get_templates()
+    pool = get_pool()
+    operator = request.state.operator
+
+    await csrf_protect.validate_csrf(request)
+
+    form = await request.form()
+    new_plaintext_key = form.get("new_plaintext_key", "")
+
+    errors: dict[str, str] = {}
+
+    # Validate new key
+    if not new_plaintext_key:
+        errors["new_plaintext_key"] = "New API key is required"
+    elif len(new_plaintext_key) > 4096:
+        errors["new_plaintext_key"] = "API key must be at most 4096 characters"
+
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            SELECT alias, created_at, rotated_at, last_used_at
+            FROM config.api_keys
+            WHERE alias = $1
+            """,
+            alias,
+        )
+
+        if row is None:
+            return Response(status_code=404, content="API key not found")
+
+        if errors:
+            adapters = await conn.fetch(
+                """
+                SELECT name FROM config.adapters
+                WHERE settings->>'api_key_alias' = $1
+                ORDER BY name
+                """,
+                alias,
+            )
+
+            key = {
+                "alias": row["alias"],
+                "created_at": row["created_at"],
+                "rotated_at": row["rotated_at"],
+                "last_used_at": row["last_used_at"],
+                "used_by": [a["name"] for a in adapters],
+            }
+
+            csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+            response = templates.TemplateResponse(
+                request=request,
+                name="api_keys_edit.html",
+                context={
+                    "operator": operator,
+                    "csrf_token": csrf_token,
+                    "key": key,
+                    "errors": errors,
+                },
+            )
+            csrf_protect.set_csrf_cookie(signed_token, response)
+            return response
+
+        old_rotated_at = row["rotated_at"]
+
+        # Encrypt the new key
+        encrypted_value = encrypt(new_plaintext_key.encode())
+
+        # Update the key
+        new_row = await conn.fetchrow(
+            """
+            UPDATE config.api_keys
+            SET encrypted_value = $1, rotated_at = now()
+            WHERE alias = $2
+            RETURNING rotated_at
+            """,
+            encrypted_value,
+            alias,
+        )
+
+        # Write audit log (no plaintext!)
+        await write_audit(
+            conn,
+            API_KEY_ROTATE,
+            operator_id=operator.id,
+            target=alias,
+            before={"rotated_at": old_rotated_at.isoformat() if old_rotated_at else None},
+            after={"rotated_at": new_row["rotated_at"].isoformat()},
+        )
+
+    return RedirectResponse(url="/api-keys", status_code=302)
+
+
+@router.post("/api-keys/{alias}/delete", response_class=HTMLResponse)
+async def api_keys_delete(
+    request: Request,
+    alias: str,
+    csrf_protect: CsrfProtect = Depends(),
+) -> Response:
+    """Delete an API key."""
+    templates = _get_templates()
+    pool = get_pool()
+    operator = request.state.operator
+
+    await csrf_protect.validate_csrf(request)
+
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            SELECT alias, created_at, rotated_at, last_used_at
+            FROM config.api_keys
+            WHERE alias = $1
+            """,
+            alias,
+        )
+
+        if row is None:
+            return Response(status_code=404, content="API key not found")
+
+        # Check for adapter references
+        adapters = await conn.fetch(
+            """
+            SELECT name FROM config.adapters
+            WHERE settings->>'api_key_alias' = $1
+            ORDER BY name
+            """,
+            alias,
+        )
+
+        if adapters:
+            adapter_names = [a["name"] for a in adapters]
+            key = {
+                "alias": row["alias"],
+                "created_at": row["created_at"],
+                "rotated_at": row["rotated_at"],
+                "last_used_at": row["last_used_at"],
+                "used_by": adapter_names,
+            }
+
+            csrf_token, signed_token = csrf_protect.generate_csrf_tokens()
+            response = templates.TemplateResponse(
+                request=request,
+                name="api_keys_edit.html",
+                context={
+                    "operator": operator,
+                    "csrf_token": csrf_token,
+                    "key": key,
+                    "error": f"Cannot delete: used by {', '.join(adapter_names)}. Remove these references first.",
+                },
+            )
+            csrf_protect.set_csrf_cookie(signed_token, response)
+            return response
+
+        # Delete the key
+        await conn.execute(
+            "DELETE FROM config.api_keys WHERE alias = $1",
+            alias,
+        )
+
+        # Write audit log (no plaintext!)
+        await write_audit(
+            conn,
+            API_KEY_DELETE,
+            operator_id=operator.id,
+            target=alias,
+            before={
+                "alias": row["alias"],
+                "created_at": row["created_at"].isoformat(),
+                "rotated_at": row["rotated_at"].isoformat() if row["rotated_at"] else None,
+            },
+            after=None,
+        )
+
+    return RedirectResponse(url="/api-keys", status_code=302)

src/central/gui/templates/api_keys_edit.html

@@ -0,0 +1,65 @@
+{% extends "base.html" %}
+
+{% block title %}Central — Manage API Key: {{ key.alias }}{% endblock %}
+
+{% block content %}
+<h1>Manage API Key: {{ key.alias }}</h1>
+
+<article>
+    <header><strong>Key Details</strong></header>
+    <ul>
+        <li><strong>Created:</strong> {{ key.created_at.strftime('%Y-%m-%d %H:%M:%S UTC') if key.created_at else '(never)' }}</li>
+        <li><strong>Last Rotated:</strong> {{ key.rotated_at.strftime('%Y-%m-%d %H:%M:%S UTC') if key.rotated_at else '(never)' }}</li>
+        <li><strong>Last Used:</strong> {{ key.last_used_at.strftime('%Y-%m-%d %H:%M:%S UTC') if key.last_used_at else '(never)' }}</li>
+        <li><strong>Used By:</strong> {% if key.used_by %}{{ key.used_by | join(', ') }}{% else %}<em>(none)</em>{% endif %}</li>
+    </ul>
+</article>
+
+<article>
+    <header><strong>Rotate Key</strong></header>
+    <p>Replace the stored API key with a new value. The old key will be permanently overwritten.</p>
+
+    <form action="/api-keys/{{ key.alias }}" method="post">
+        <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+
+        <label for="new_plaintext_key">New API Key</label>
+        <input type="password" id="new_plaintext_key" name="new_plaintext_key"
+               placeholder="Paste your new API key here" required maxlength="4096"
+               aria-invalid="{{ 'true' if errors and errors.new_plaintext_key else 'false' }}">
+        {% if errors and errors.new_plaintext_key %}
+        <small style="color: var(--pico-color-red-500);">{{ errors.new_plaintext_key }}</small>
+        {% else %}
+        <small>The key will be encrypted before storage.</small>
+        {% endif %}
+
+        <button type="submit">Rotate Key</button>
+    </form>
+</article>
+
+<article>
+    <header><strong>Delete Key</strong></header>
+
+    {% if key.used_by %}
+    <p style="color: var(--pico-color-red-500);">
+        <strong>Cannot delete:</strong> This key is used by: {{ key.used_by | join(', ') }}.
+        Remove these references from the adapters first.
+    </p>
+    <form>
+        <button type="button" disabled>Delete Key</button>
+    </form>
+    {% else %}
+    <p>Permanently delete this API key. This action cannot be undone.</p>
+
+    {% if error %}
+    <p style="color: var(--pico-color-red-500);">{{ error }}</p>
+    {% endif %}
+
+    <form action="/api-keys/{{ key.alias }}/delete" method="post">
+        <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+        <button type="submit" class="contrast">Delete Key</button>
+    </form>
+    {% endif %}
+</article>
+
+<p><a href="/api-keys">&larr; Back to API Keys</a></p>
+{% endblock %}

src/central/gui/templates/api_keys_list.html

@@ -0,0 +1,40 @@
+{% extends "base.html" %}
+
+{% block title %}Central — API Keys{% endblock %}
+
+{% block content %}
+<h1>API Keys</h1>
+
+<p><a href="/api-keys/new" role="button">Add New Key</a></p>
+
+{% if keys %}
+<table>
+    <thead>
+        <tr>
+            <th>Alias</th>
+            <th>Created</th>
+            <th>Rotated</th>
+            <th>Last Used</th>
+            <th>In Use By</th>
+            <th>Actions</th>
+        </tr>
+    </thead>
+    <tbody>
+        {% for key in keys %}
+        <tr>
+            <td><strong>{{ key.alias }}</strong></td>
+            <td>{{ key.created_at.strftime('%Y-%m-%d %H:%M') if key.created_at else '(never)' }}</td>
+            <td>{{ key.rotated_at.strftime('%Y-%m-%d %H:%M') if key.rotated_at else '(never)' }}</td>
+            <td>{{ key.last_used_at.strftime('%Y-%m-%d %H:%M') if key.last_used_at else '(never)' }}</td>
+            <td>{% if key.used_by %}{{ key.used_by | join(', ') }}{% else %}<em>(none)</em>{% endif %}</td>
+            <td>
+                <a href="/api-keys/{{ key.alias }}" role="button" class="outline" style="padding: 0.3em 0.6em; font-size: 0.9em;">Manage</a>
+            </td>
+        </tr>
+        {% endfor %}
+    </tbody>
+</table>
+{% else %}
+<p>No API keys configured.</p>
+{% endif %}
+{% endblock %}

src/central/gui/templates/api_keys_new.html

@@ -0,0 +1,36 @@
+{% extends "base.html" %}
+
+{% block title %}Central — Add API Key{% endblock %}
+
+{% block content %}
+<h1>Add API Key</h1>
+
+<form action="/api-keys" method="post">
+    <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+
+    <label for="alias">Alias</label>
+    <input type="text" id="alias" name="alias" value="{{ alias | default('', true) }}"
+           placeholder="e.g., firms_production" required maxlength="64"
+           aria-invalid="{{ 'true' if errors and errors.alias else 'false' }}">
+    {% if errors and errors.alias %}
+    <small style="color: var(--pico-color-red-500);">{{ errors.alias }}</small>
+    {% else %}
+    <small>Letters, numbers, and underscores only. Max 64 characters.</small>
+    {% endif %}
+
+    <label for="plaintext_key">API Key</label>
+    <input type="password" id="plaintext_key" name="plaintext_key"
+           placeholder="Paste your API key here" required maxlength="4096"
+           aria-invalid="{{ 'true' if errors and errors.plaintext_key else 'false' }}">
+    {% if errors and errors.plaintext_key %}
+    <small style="color: var(--pico-color-red-500);">{{ errors.plaintext_key }}</small>
+    {% else %}
+    <small>The key will be encrypted before storage. You will not be able to view it again.</small>
+    {% endif %}
+
+    <div style="display: flex; gap: 1rem; margin-top: 1rem;">
+        <button type="submit">Save Key</button>
+        <a href="/api-keys" role="button" class="outline">Cancel</a>
+    </div>
+</form>
+{% endblock %}

src/central/gui/templates/base.html

@@ -18,6 +18,7 @@
             <li><a href="/">Dashboard</a></li>
             <li><a href="/adapters">Adapters</a></li>
             <li><a href="/streams">Streams</a></li>
+            <li><a href="/api-keys">API Keys</a></li>
             <li>{{ operator.username }}</li>
             <li><a href="/change-password">Change Password</a></li>
             <li>

tests/test_api_keys.py

@@ -0,0 +1,421 @@
+"""Tests for API keys management routes."""
+
+import os
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from central.gui.routes import (
+    api_keys_list,
+    api_keys_new,
+    api_keys_create,
+    api_keys_edit,
+    api_keys_rotate,
+    api_keys_delete,
+)
+
+
+class TestApiKeysListUnauthenticated:
+    """Test API keys list without authentication."""
+
+    @pytest.mark.asyncio
+    async def test_api_keys_list_unauthenticated_redirects(self):
+        """GET /api-keys without auth redirects to /login."""
+        # This test verifies the session middleware behavior
+        # In practice, the middleware redirects before the route is called
+        # We verify the route requires operator in request.state
+        mock_request = MagicMock()
+        mock_request.state.operator = None
+
+        # The middleware would redirect, but if it didn't,
+        # the route would fail trying to access operator.id
+        # This is tested via the session middleware tests
+
+
+class TestApiKeysListAuthenticated:
+    """Test API keys list with authentication."""
+
+    @pytest.mark.asyncio
+    async def test_api_keys_list_returns_all_keys_with_usage(self):
+        """GET /api-keys authenticated returns 200 with all keys and usage info."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        mock_templates = MagicMock()
+        mock_templates.TemplateResponse.return_value = MagicMock()
+
+        # Mock database
+        mock_conn = AsyncMock()
+
+        # Keys query result
+        mock_conn.fetch.side_effect = [
+            # First call: keys
+            [
+                {
+                    "alias": "firms",
+                    "created_at": datetime(2026, 5, 16, 20, 0, tzinfo=timezone.utc),
+                    "rotated_at": None,
+                    "last_used_at": datetime(2026, 5, 17, 12, 0, tzinfo=timezone.utc),
+                },
+                {
+                    "alias": "test_key",
+                    "created_at": datetime(2026, 5, 17, 10, 0, tzinfo=timezone.utc),
+                    "rotated_at": None,
+                    "last_used_at": None,
+                },
+            ],
+            # Second call: adapters using firms
+            [{"name": "firms"}],
+            # Third call: adapters using test_key
+            [],
+        ]
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.generate_csrf_tokens.return_value = ("token", "signed")
+        mock_csrf.set_csrf_cookie = MagicMock()
+
+        with patch("central.gui.routes._get_templates", return_value=mock_templates):
+            with patch("central.gui.routes.get_pool", return_value=mock_pool):
+                result = await api_keys_list(mock_request, mock_csrf)
+
+        # Check template was called with correct context
+        call_args = mock_templates.TemplateResponse.call_args
+        context = call_args.kwargs.get("context", call_args[1].get("context"))
+
+        assert len(context["keys"]) == 2
+        firms_key = next(k for k in context["keys"] if k["alias"] == "firms")
+        assert firms_key["used_by"] == ["firms"]
+
+        test_key = next(k for k in context["keys"] if k["alias"] == "test_key")
+        assert test_key["used_by"] == []
+
+
+class TestApiKeysCreate:
+    """Test API key creation."""
+
+    @pytest.mark.asyncio
+    async def test_create_valid_key_redirects(self):
+        """POST /api-keys with valid data creates key and redirects."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        form_data = {"alias": "test1", "plaintext_key": "secret-api-key-123"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_conn = AsyncMock()
+        # Check existing - not found
+        mock_conn.fetchrow.side_effect = [
+            None,  # No existing key
+            {"created_at": datetime(2026, 5, 18, 12, 0, tzinfo=timezone.utc)},  # Insert result
+        ]
+        mock_conn.execute = AsyncMock()
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+
+        with patch("central.gui.routes.get_pool", return_value=mock_pool):
+            with patch("central.crypto.encrypt", return_value=b"encrypted_data"):
+                with patch("central.gui.routes.write_audit", new_callable=AsyncMock):
+                    result = await api_keys_create(mock_request, mock_csrf)
+
+        assert result.status_code == 302
+        assert result.headers["location"] == "/api-keys"
+
+    @pytest.mark.asyncio
+    async def test_create_existing_alias_shows_error(self):
+        """POST /api-keys with existing alias shows error."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        form_data = {"alias": "firms", "plaintext_key": "secret-key"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_templates = MagicMock()
+        mock_templates.TemplateResponse.return_value = MagicMock()
+
+        mock_conn = AsyncMock()
+        # Key already exists
+        mock_conn.fetchrow.return_value = {"alias": "firms"}
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+        mock_csrf.generate_csrf_tokens.return_value = ("token", "signed")
+        mock_csrf.set_csrf_cookie = MagicMock()
+
+        with patch("central.gui.routes._get_templates", return_value=mock_templates):
+            with patch("central.gui.routes.get_pool", return_value=mock_pool):
+                with patch("central.crypto.encrypt", return_value=b"encrypted"):
+                    result = await api_keys_create(mock_request, mock_csrf)
+
+        # Should re-render form with error
+        call_args = mock_templates.TemplateResponse.call_args
+        context = call_args.kwargs.get("context", call_args[1].get("context"))
+        assert "errors" in context
+        assert "alias" in context["errors"]
+
+    @pytest.mark.asyncio
+    async def test_create_empty_alias_shows_error(self):
+        """POST /api-keys with empty alias shows error."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        form_data = {"alias": "", "plaintext_key": "secret-key"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_templates = MagicMock()
+        mock_templates.TemplateResponse.return_value = MagicMock()
+
+        mock_conn = AsyncMock()
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+        mock_csrf.generate_csrf_tokens.return_value = ("token", "signed")
+        mock_csrf.set_csrf_cookie = MagicMock()
+
+        with patch("central.gui.routes._get_templates", return_value=mock_templates):
+            with patch("central.gui.routes.get_pool", return_value=mock_pool):
+                result = await api_keys_create(mock_request, mock_csrf)
+
+        call_args = mock_templates.TemplateResponse.call_args
+        context = call_args.kwargs.get("context", call_args[1].get("context"))
+        assert context["errors"]["alias"] == "Alias is required"
+
+    @pytest.mark.asyncio
+    async def test_create_invalid_alias_chars_shows_error(self):
+        """POST /api-keys with invalid alias chars shows error."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        # Test with space
+        form_data = {"alias": "test key", "plaintext_key": "secret-key"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_templates = MagicMock()
+        mock_templates.TemplateResponse.return_value = MagicMock()
+
+        mock_conn = AsyncMock()
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+        mock_csrf.generate_csrf_tokens.return_value = ("token", "signed")
+        mock_csrf.set_csrf_cookie = MagicMock()
+
+        with patch("central.gui.routes._get_templates", return_value=mock_templates):
+            with patch("central.gui.routes.get_pool", return_value=mock_pool):
+                result = await api_keys_create(mock_request, mock_csrf)
+
+        call_args = mock_templates.TemplateResponse.call_args
+        context = call_args.kwargs.get("context", call_args[1].get("context"))
+        assert "letters, numbers, and underscores" in context["errors"]["alias"]
+
+    @pytest.mark.asyncio
+    async def test_create_hyphen_in_alias_shows_error(self):
+        """POST /api-keys with hyphen in alias shows error."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        form_data = {"alias": "test-key", "plaintext_key": "secret-key"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_templates = MagicMock()
+        mock_templates.TemplateResponse.return_value = MagicMock()
+
+        mock_conn = AsyncMock()
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+        mock_csrf.generate_csrf_tokens.return_value = ("token", "signed")
+        mock_csrf.set_csrf_cookie = MagicMock()
+
+        with patch("central.gui.routes._get_templates", return_value=mock_templates):
+            with patch("central.gui.routes.get_pool", return_value=mock_pool):
+                result = await api_keys_create(mock_request, mock_csrf)
+
+        call_args = mock_templates.TemplateResponse.call_args
+        context = call_args.kwargs.get("context", call_args[1].get("context"))
+        assert "alias" in context["errors"]
+
+
+class TestApiKeysRotate:
+    """Test API key rotation."""
+
+    @pytest.mark.asyncio
+    async def test_rotate_updates_key_and_timestamp(self):
+        """POST /api-keys/{alias} rotates key and updates rotated_at."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        form_data = {"new_plaintext_key": "new-secret-key-456"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_conn = AsyncMock()
+        old_time = datetime(2026, 5, 17, 10, 0, tzinfo=timezone.utc)
+        new_time = datetime(2026, 5, 18, 12, 0, tzinfo=timezone.utc)
+
+        mock_conn.fetchrow.side_effect = [
+            # First: get existing key
+            {
+                "alias": "test1",
+                "created_at": datetime(2026, 5, 16, 10, 0, tzinfo=timezone.utc),
+                "rotated_at": old_time,
+                "last_used_at": None,
+            },
+            # Second: update result
+            {"rotated_at": new_time},
+        ]
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+
+        with patch("central.gui.routes.get_pool", return_value=mock_pool):
+            with patch("central.crypto.encrypt", return_value=b"new_encrypted"):
+                with patch("central.gui.routes.write_audit", new_callable=AsyncMock) as mock_audit:
+                    result = await api_keys_rotate(mock_request, "test1", mock_csrf)
+
+        assert result.status_code == 302
+        # Check audit was called with no plaintext
+        mock_audit.assert_called_once()
+        audit_call = mock_audit.call_args
+        assert "new-secret-key" not in str(audit_call)
+
+
+class TestApiKeysDelete:
+    """Test API key deletion."""
+
+    @pytest.mark.asyncio
+    async def test_delete_with_references_shows_error(self):
+        """POST /api-keys/{alias}/delete with references shows error."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        mock_templates = MagicMock()
+        mock_templates.TemplateResponse.return_value = MagicMock()
+
+        mock_conn = AsyncMock()
+        mock_conn.fetchrow.return_value = {
+            "alias": "firms",
+            "created_at": datetime(2026, 5, 16, 10, 0, tzinfo=timezone.utc),
+            "rotated_at": None,
+            "last_used_at": None,
+        }
+        # Adapters using the key
+        mock_conn.fetch.return_value = [{"name": "firms"}]
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+        mock_csrf.generate_csrf_tokens.return_value = ("token", "signed")
+        mock_csrf.set_csrf_cookie = MagicMock()
+
+        with patch("central.gui.routes._get_templates", return_value=mock_templates):
+            with patch("central.gui.routes.get_pool", return_value=mock_pool):
+                result = await api_keys_delete(mock_request, "firms", mock_csrf)
+
+        # Should re-render with error
+        call_args = mock_templates.TemplateResponse.call_args
+        context = call_args.kwargs.get("context", call_args[1].get("context"))
+        assert "error" in context
+        assert "firms" in context["error"]
+
+    @pytest.mark.asyncio
+    async def test_delete_without_references_succeeds(self):
+        """POST /api-keys/{alias}/delete without references deletes and redirects."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        mock_conn = AsyncMock()
+        mock_conn.fetchrow.return_value = {
+            "alias": "test1",
+            "created_at": datetime(2026, 5, 16, 10, 0, tzinfo=timezone.utc),
+            "rotated_at": None,
+            "last_used_at": None,
+        }
+        # No adapters using the key
+        mock_conn.fetch.return_value = []
+        mock_conn.execute = AsyncMock()
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+
+        with patch("central.gui.routes.get_pool", return_value=mock_pool):
+            with patch("central.gui.routes.write_audit", new_callable=AsyncMock) as mock_audit:
+                result = await api_keys_delete(mock_request, "test1", mock_csrf)
+
+        assert result.status_code == 302
+        assert result.headers["location"] == "/api-keys"
+        mock_conn.execute.assert_called_once()
+
+
+class TestApiKeysAuditNoPlaintext:
+    """Test that audit logs never contain plaintext keys."""
+
+    @pytest.mark.asyncio
+    async def test_create_audit_has_no_plaintext(self):
+        """Verify create audit log doesn't contain plaintext."""
+        mock_request = MagicMock()
+        mock_request.state.operator = MagicMock(id=1, username="admin")
+
+        form_data = {"alias": "newkey", "plaintext_key": "super-secret-value"}
+        mock_request.form = AsyncMock(return_value=form_data)
+
+        mock_conn = AsyncMock()
+        mock_conn.fetchrow.side_effect = [
+            None,
+            {"created_at": datetime(2026, 5, 18, 12, 0, tzinfo=timezone.utc)},
+        ]
+
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__aenter__.return_value = mock_conn
+        mock_pool.acquire.return_value.__aexit__.return_value = None
+
+        mock_csrf = MagicMock()
+        mock_csrf.validate_csrf = AsyncMock()
+
+        with patch("central.gui.routes.get_pool", return_value=mock_pool):
+            with patch("central.crypto.encrypt", return_value=b"encrypted"):
+                with patch("central.gui.routes.write_audit", new_callable=AsyncMock) as mock_audit:
+                    await api_keys_create(mock_request, mock_csrf)
+
+        # Check audit call arguments
+        call_kwargs = mock_audit.call_args.kwargs
+        before = call_kwargs.get("before")
+        after = call_kwargs.get("after")
+
+        # Plaintext should not appear
+        assert before is None or "super-secret-value" not in str(before)
+        assert "super-secret-value" not in str(after)
+        # encrypted value should not appear either
+        assert "encrypted" not in str(after)