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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Let GET /api/v1/servers accept a scoped API key
Juan Denis93a3cd783e36
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 reachingdiff --git a/backend/app/api/servers.py b/backend/app/api/servers.pyindex 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_commandfrom app.services.agent_fleet_service import fleet_servicefrom app.services.discovery_service import discovery_servicefrom 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_scopefrom 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 parametersgroup_id = request.args.get('group_id')status = request.args.get('status')diff --git a/backend/tests/JWT_ONLY_CEILING b/backend/tests/JWT_ONLY_CEILINGindex 75a2e0d5..e9f960cf 100644--- a/backend/tests/JWT_ONLY_CEILING+++ b/backend/tests/JWT_ONLY_CEILING@@ -1 +1 @@-601+600diff --git a/backend/tests/test_servers_api_key_scope.py b/backend/tests/test_servers_api_key_scope.pynew file mode 100644index 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 == 401diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.mdindex 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 |