Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Let GET /api/v1/servers accept a scoped API key

Juan Denis93a3cd783e36
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 627b2c1d..033f117e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,14 @@ release history; historical `agent-v*` tags are not panel releases.
## [Unreleased]
+### Added
+
+- `GET /api/v1/servers` now accepts an API key (`X-API-Key`) carrying the
+ `servers:read` scope, in addition to the usual JWT, so external tools can
+ poll the server list read-only without a short-lived token. JWT callers are
+ unaffected; keys without the scope are refused. The Agent GUI extension's
+ read routes (`capabilities`, `frame`, `surface`) accept the same scope.
+
### Security
- Require a one-time setup code to create the first administrator, so reaching
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index d8cda7a6..b0483219 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -24,7 +24,8 @@ from app.services.remote_command_dispatcher import dispatch_agent_command
from app.services.agent_fleet_service import fleet_service
from app.services.discovery_service import discovery_service
from app.services import connection_string as connection_string_codec
-from app.middleware.rbac import admin_required, developer_required, get_current_user
+from app.middleware.rbac import admin_required, auth_required, developer_required, get_current_user
+from app.middleware.api_scope_middleware import require_scope
from app.exceptions import ValidationError
@@ -258,9 +259,15 @@ def delete_group(group_id):
# ==================== Servers ====================
@servers_bp.route('', methods=['GET'])
-@jwt_required()
+@auth_required()
+@require_scope('servers:read')
def list_servers():
- """List all servers"""
+ """List all servers.
+
+ API-key capable by deliberate decision (jwt_only_census exception):
+ a Vela host holds one scoped ServerKit key and polls this route, so
+ an X-API-Key with the servers:read scope is accepted alongside JWT.
+ """
# Query parameters
group_id = request.args.get('group_id')
status = request.args.get('status')
diff --git a/backend/tests/JWT_ONLY_CEILING b/backend/tests/JWT_ONLY_CEILING
index 75a2e0d5..e9f960cf 100644
--- a/backend/tests/JWT_ONLY_CEILING
+++ b/backend/tests/JWT_ONLY_CEILING
@@ -1 +1 @@
-601
+600
diff --git a/backend/tests/test_servers_api_key_scope.py b/backend/tests/test_servers_api_key_scope.py
new file mode 100644
index 00000000..046e88c8
--- /dev/null
+++ b/backend/tests/test_servers_api_key_scope.py
@@ -0,0 +1,40 @@
+"""GET /api/v1/servers accepts a scoped API key (deliberate conversion).
+
+A Vela host holds one ServerKit API key as a host-side secret and polls the
+fleet list, so this read route takes a JWT *or* an ``X-API-Key`` carrying the
+``servers:read`` scope. That is a recorded jwt_only_census exception — JWT-only
+stays the default elsewhere (see tests/jwt_only_census.py); these tests pin
+the behavior of the exception itself.
+"""
+from factories import make_user, headers_for
+from app.services.api_key_service import ApiKeyService
+
+
+def _api_key_headers(db, scopes):
+ user = make_user(db)
+ _, raw_key = ApiKeyService.create_key(user.id, name='servers-poll', scopes=scopes)
+ return {'X-API-Key': raw_key}
+
+
+def test_api_key_with_servers_read_scope_lists_servers(client, db_session):
+ resp = client.get('/api/v1/servers',
+ headers=_api_key_headers(db_session, ['servers:read']))
+ assert resp.status_code == 200
+ assert isinstance(resp.json, list)
+
+
+def test_api_key_without_the_scope_is_denied(client, db_session):
+ resp = client.get('/api/v1/servers',
+ headers=_api_key_headers(db_session, ['databases:read']))
+ assert resp.status_code == 403
+
+
+def test_jwt_caller_still_lists_servers(client, db_session):
+ resp = client.get('/api/v1/servers',
+ headers=headers_for(make_user(db_session)))
+ assert resp.status_code == 200
+ assert isinstance(resp.json, list)
+
+
+def test_unauthenticated_gets_401(client):
+ assert client.get('/api/v1/servers').status_code == 401
diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.md
index 76434908..5f91bbb9 100644
--- a/docs/MIGRATION_INVENTORY.md
+++ b/docs/MIGRATION_INVENTORY.md
@@ -13,7 +13,7 @@ debt. Regenerate with `python scripts/generate-migration-inventory.py`.
| Concern | Door | Remaining | Ceiling | Policy |
|---|---|---:|---:|---|
| Identity lookups outside rbac.get_current_user() | rbac.get_current_user() | 69 | 69 | JWT-only routes; the API-key-capable population is held at 0 by a companion assertion |
-| Routes on bare @jwt_required() | auth_required() / role decorators | 601 | 601 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
+| Routes on bare @jwt_required() | auth_required() / role decorators | 600 | 600 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
| HTTP statuses chosen by sniffing error text | typed errors from app.exceptions | 0 | 0 | INVARIANT at 0 - migration completed 2026-08-19 |
| API crashes swallowed without recording | app.error_reporting | 0 | 0 | INVARIANT at 0 |
| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 1132 | 1150 | migrate when touched; new endpoints raise |