Feat: Implement API key authentication (#84)

* feat(auth): Implement API key authentication

This commit enables API access with an API key system. This change provides a better experience for programmatic access and third-party integrations.

Key changes include:
- **API Key Management:** Users can now generate, manage, and revoke persistent API keys through a new "API Keys" section in the settings UI.
- **Authentication Middleware:** API requests are now authenticated via an `X-API-KEY` header instead of the previous `Authorization: Bearer` token.
- **Backend Implementation:** Adds a new `api_keys` database table, along with corresponding services, controllers, and routes to manage the key lifecycle securely.
- **Rate Limiting:** The API rate limiter now uses the API key to identify and track requests.
- **Documentation:** The API authentication documentation has been updated to reflect the new method.

* Add configurable API rate limiting

Two new variables are added to `.env.example`:
- `RATE_LIMIT_WINDOW_MS`: The time window in milliseconds for which requests are checked (defaults to 15 minutes).
- `RATE_LIMIT_MAX_REQUESTS`: The maximum number of requests allowed from an IP within the window (defaults to 100).

The installation documentation has been updated to reflect these new configuration options.

---------

Co-authored-by: Wayne <5291640+ringoinca@users.noreply.github.com>

.env.example

@@ -54,6 +54,12 @@ STORAGE_S3_FORCE_PATH_STYLE=false
 
 # --- Security & Authentication ---
 
+# Rate Limiting
+# The window in milliseconds for which API requests are checked. Defaults to 900000 (15 minutes).
+RATE_LIMIT_WINDOW_MS=900000
+# The maximum number of API requests allowed from an IP within the window. Defaults to 100.
+RATE_LIMIT_MAX_REQUESTS=100
+
 # JWT
 # IMPORTANT: Change this to a long, random, and secret string in your .env file
 JWT_SECRET=a-very-secret-key-that-you-should-change
@@ -64,5 +70,3 @@ JWT_EXPIRES_IN="7d"
 # IMPORTANT: Generate a secure, random 32-byte hex string for this
 # You can use `openssl rand -hex 32` to generate a key.
 ENCRYPTION_KEY=
-
-

docs/api/authentication.md

@@ -1,45 +1,25 @@
 # API Authentication
 
-To access protected API endpoints, you need to include a JSON Web Token (JWT) in the `Authorization` header of your requests.
+To access protected API endpoints, you need to include a user-generated API key in the `X-API-KEY` header of your requests.
 
-## Obtaining a JWT
+## 1. Creating an API Key
 
-First, you need to authenticate with the `/api/v1/auth/login` endpoint by providing your email and password. If the credentials are correct, the API will return an `accessToken`.
+You can create, manage, and view your API keys through the application's user interface.
 
-**Request:**
+1.  Navigate to **Settings > API Keys** in the dashboard.
+2.  Click the **"Generate API Key"** button.
+3.  Provide a descriptive name for your key and select an expiration period.
+4.  The new API key will be displayed. **Copy this key immediately and store it in a secure location. You will not be able to see it again.**
 
-```http
-POST /api/v1/auth/login
-Content-Type: application/json
+## 2. Making Authenticated Requests
 
-{
-  "email": "user@example.com",
-  "password": "your-password"
-}
-```
-
-**Successful Response:**
-
-```json
-{
-	"accessToken": "your.jwt.token",
-	"user": {
-		"id": "user-id",
-		"email": "user@example.com",
-		"role": "user"
-	}
-}
-```
-
-## Making Authenticated Requests
-
-Once you have the `accessToken`, you must include it in the `Authorization` header of all subsequent requests to protected endpoints, using the `Bearer` scheme.
+Once you have your API key, you must include it in the `X-API-KEY` header of all subsequent requests to protected API endpoints.
 
 **Example:**
 
 ```http
 GET /api/v1/dashboard/stats
-Authorization: Bearer your.jwt.token
+X-API-KEY: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
 ```
 
-If the token is missing, expired, or invalid, the API will respond with a `401 Unauthorized` status code.
+If the API key is missing, expired, or invalid, the API will respond with a `401 Unauthorized` status code.

docs/user-guides/installation.md

@@ -110,6 +110,8 @@ These variables are used by `docker-compose.yml` to configure the services.
 | `JWT_SECRET`                     | A secret key for signing JWT tokens.                                                                                                           | `a-very-secret-key-that-you-should-change` |
 | `JWT_EXPIRES_IN`                 | The expiration time for JWT tokens.                                                                                                            | `7d`                                       |
 | ~~`SUPER_API_KEY`~~ (Deprecated) | An API key with super admin privileges. (The SUPER_API_KEY is deprecated since v0.3.0 after we roll out the role-based access control system.) |                                            |
+| `RATE_LIMIT_WINDOW_MS`           | The window in milliseconds for which API requests are checked.                                                                                 | `900000` (15 minutes)                      |
+| `RATE_LIMIT_MAX_REQUESTS`        | The maximum number of API requests allowed from an IP within the window.                                                                       | `100`                                      |
 | `ENCRYPTION_KEY`                 | A 32-byte hex string for encrypting sensitive data in the database.                                                                            |                                            |
 
 ## 3. Run the Application

packages/backend/package.json

@@ -60,7 +60,8 @@
 		"sqlite3": "^5.1.7",
 		"tsconfig-paths": "^4.2.0",
 		"xlsx": "^0.18.5",
-		"yauzl": "^3.2.0"
+		"yauzl": "^3.2.0",
+		"zod": "^4.1.5"
 	},
 	"devDependencies": {
 		"@bull-board/api": "^6.11.0",

packages/backend/src/api/controllers/api-key.controller.ts

@@ -0,0 +1,50 @@
+import { Request, Response } from 'express';
+import { ApiKeyService } from '../../services/ApiKeyService';
+import { z } from 'zod';
+
+const generateApiKeySchema = z.object({
+    name: z.string().min(1, 'API kay name must be more than 1 characters').max(255, 'API kay name must not be more than 255 characters'),
+    expiresInDays: z.number().int().positive('Only positive number is allowed').max(730, "The API key must expire within 2 years / 730 days."),
+});
+
+export class ApiKeyController {
+    public async generateApiKey(req: Request, res: Response) {
+        try {
+            const { name, expiresInDays } = generateApiKeySchema.parse(req.body);
+            if (!req.user || !req.user.sub) {
+                return res.status(401).json({ message: 'Unauthorized' });
+            }
+            const userId = req.user.sub;
+
+            const key = await ApiKeyService.generate(userId, name, expiresInDays);
+
+            res.status(201).json({ key });
+        } catch (error) {
+            if (error instanceof z.ZodError) {
+                return res.status(400).json({ message: req.t('api.requestBodyInvalid'), errors: error.message });
+            }
+            res.status(500).json({ message: req.t('errors.internalServerError') });
+        }
+    }
+
+    public async getApiKeys(req: Request, res: Response) {
+        if (!req.user || !req.user.sub) {
+            return res.status(401).json({ message: 'Unauthorized' });
+        }
+        const userId = req.user.sub;
+        const keys = await ApiKeyService.getKeys(userId);
+
+        res.status(200).json(keys);
+    }
+
+    public async deleteApiKey(req: Request, res: Response) {
+        const { id } = req.params;
+        if (!req.user || !req.user.sub) {
+            return res.status(401).json({ message: 'Unauthorized' });
+        }
+        const userId = req.user.sub;
+        await ApiKeyService.deleteKey(id, userId);
+
+        res.status(204).send({ message: req.t('apiKeys.deleteSuccess') });
+    }
+}

packages/backend/src/api/controllers/settings.controller.ts

@@ -4,9 +4,9 @@ import { config } from '../../config';
 
 const settingsService = new SettingsService();
 
-export const getSettings = async (req: Request, res: Response) => {
+export const getSystemSettings = async (req: Request, res: Response) => {
 	try {
-		const settings = await settingsService.getSettings();
+		const settings = await settingsService.getSystemSettings();
 		res.status(200).json(settings);
 	} catch (error) {
 		// A more specific error could be logged here
@@ -14,13 +14,13 @@ export const getSettings = async (req: Request, res: Response) => {
 	}
 };
 
-export const updateSettings = async (req: Request, res: Response) => {
+export const updateSystemSettings = async (req: Request, res: Response) => {
 	try {
 		// Basic validation can be performed here if necessary
 		if (config.app.isDemo) {
 			return res.status(403).json({ message: req.t('errors.demoMode') });
 		}
-		const updatedSettings = await settingsService.updateSettings(req.body);
+		const updatedSettings = await settingsService.updateSystemSettings(req.body);
 		res.status(200).json(updatedSettings);
 	} catch (error) {
 		// A more specific error could be logged here

packages/backend/src/api/middleware/rateLimiter.ts

@@ -1,10 +1,12 @@
 import rateLimit from 'express-rate-limit';
+import { config } from '../../config';
 
-// Rate limiter to prevent brute-force attacks on the login endpoint
-export const loginRateLimiter = rateLimit({
-	windowMs: 15 * 60 * 1000, // 15 minutes
-	max: 10, // Limit each IP to 10 login requests per windowMs
-	message: 'Too many login attempts from this IP, please try again after 15 minutes',
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+const windowInMinutes = Math.ceil(config.api.rateLimit.windowMs / 60000);
+
+export const rateLimiter = rateLimit({
+	windowMs: config.api.rateLimit.windowMs,
+	max: config.api.rateLimit.max,
+	message: `Too many requests from this IP, please try again after ${windowInMinutes} minutes`,
+	standardHeaders: true,
+	legacyHeaders: false,
 });

packages/backend/src/api/middleware/requireAuth.ts

@@ -2,6 +2,9 @@ import type { Request, Response, NextFunction } from 'express';
 import type { AuthService } from '../../services/AuthService';
 import type { AuthTokenPayload } from '@open-archiver/types';
 import 'dotenv/config';
+import { ApiKeyService } from '../../services/ApiKeyService';
+import { UserService } from '../../services/UserService';
+
 // By using module augmentation, we can add our custom 'user' property
 // to the Express Request interface in a type-safe way.
 declare global {
@@ -15,6 +18,25 @@ declare global {
 export const requireAuth = (authService: AuthService) => {
 	return async (req: Request, res: Response, next: NextFunction) => {
 		const authHeader = req.headers.authorization;
+		const apiKeyHeader = req.headers['x-api-key'];
+
+		if (apiKeyHeader) {
+			const userId = await ApiKeyService.validateKey(apiKeyHeader as string);
+			if (!userId) {
+				return res.status(401).json({ message: 'Unauthorized: Invalid API key' });
+			}
+			const user = await new UserService().findById(userId);
+			if (!user) {
+				return res.status(401).json({ message: 'Unauthorized: Invalid user' });
+			}
+			req.user = {
+				sub: user.id,
+				email: user.email,
+				roles: user.role ? [user.role.name] : []
+			};
+			return next();
+		}
+
 		if (!authHeader || !authHeader.startsWith('Bearer ')) {
 			return res.status(401).json({ message: 'Unauthorized: No token provided' });
 		}

packages/backend/src/api/routes/api-key.routes.ts

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+import { ApiKeyController } from '../controllers/api-key.controller';
+import { requireAuth } from '../middleware/requireAuth';
+import { AuthService } from '../../services/AuthService';
+
+export const apiKeyRoutes = (authService: AuthService) => {
+    const router = Router();
+    const controller = new ApiKeyController();
+
+    router.post('/', requireAuth(authService), controller.generateApiKey);
+    router.get('/', requireAuth(authService), controller.getApiKeys);
+    router.delete('/:id', requireAuth(authService), controller.deleteApiKey);
+
+    return router;
+};

packages/backend/src/api/routes/auth.routes.ts

@@ -1,5 +1,4 @@
 import { Router } from 'express';
-import { loginRateLimiter } from '../middleware/rateLimiter';
 import type { AuthController } from '../controllers/auth.controller';
 
 export const createAuthRouter = (authController: AuthController): Router => {
@@ -10,14 +9,14 @@ export const createAuthRouter = (authController: AuthController): Router => {
 	 * @description Creates the initial administrator user.
 	 * @access Public
 	 */
-	router.post('/setup', loginRateLimiter, authController.setup);
+	router.post('/setup', authController.setup);
 
 	/**
 	 * @route POST /api/v1/auth/login
 	 * @description Authenticates a user and returns a JWT.
 	 * @access Public
 	 */
-	router.post('/login', loginRateLimiter, authController.login);
+	router.post('/login', authController.login);
 
 	/**
 	 * @route GET /api/v1/auth/status

packages/backend/src/api/routes/settings.routes.ts

@@ -11,14 +11,14 @@ export const createSettingsRouter = (authService: AuthService): Router => {
 	/**
 	 * @returns SystemSettings
 	 */
-	router.get('/', settingsController.getSettings);
+	router.get('/system', settingsController.getSystemSettings);
 
 	// Protected route to update settings
 	router.put(
-		'/',
+		'/system',
 		requireAuth(authService),
 		requirePermission('manage', 'settings', 'settings.noPermissionToUpdate'),
-		settingsController.updateSettings
+		settingsController.updateSystemSettings
 	);
 
 	return router;

packages/backend/src/config/api.ts

@@ -0,0 +1,8 @@
+import 'dotenv/config';
+
+export const apiConfig = {
+    rateLimit: {
+        windowMs: process.env.RATE_LIMIT_WINDOW_MS ? parseInt(process.env.RATE_LIMIT_WINDOW_MS, 10) : 15 * 60 * 1000, // 15 minutes
+        max: process.env.RATE_LIMIT_MAX_REQUESTS ? parseInt(process.env.RATE_LIMIT_MAX_REQUESTS, 10) : 100, // limit each IP to 100 requests per windowMs
+    }
+};

packages/backend/src/config/index.ts

@@ -2,10 +2,12 @@ import { storage } from './storage';
 import { app } from './app';
 import { searchConfig } from './search';
 import { connection as redisConfig } from './redis';
+import { apiConfig } from './api';
 
 export const config = {
 	storage,
 	app,
 	search: searchConfig,
 	redis: redisConfig,
+	api: apiConfig,
 };

packages/backend/src/database/migrations/0018_flawless_owl.sql

@@ -0,0 +1,11 @@
+CREATE TABLE "api_keys" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"user_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "api_keys" ADD CONSTRAINT "api_keys_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;

packages/backend/src/database/migrations/0019_confused_scream.sql

@@ -0,0 +1 @@
+ALTER TABLE "api_keys" ADD COLUMN "key_hash" text NOT NULL;

packages/backend/src/database/migrations/meta/_journal.json

@@ -1,132 +1,146 @@
 {
-	"version": "7",
-	"dialect": "postgresql",
-	"entries": [
-		{
-			"idx": 0,
-			"version": "7",
-			"when": 1752225352591,
-			"tag": "0000_amusing_namora",
-			"breakpoints": true
-		},
-		{
-			"idx": 1,
-			"version": "7",
-			"when": 1752326803882,
-			"tag": "0001_odd_night_thrasher",
-			"breakpoints": true
-		},
-		{
-			"idx": 2,
-			"version": "7",
-			"when": 1752332648392,
-			"tag": "0002_lethal_quentin_quire",
-			"breakpoints": true
-		},
-		{
-			"idx": 3,
-			"version": "7",
-			"when": 1752332967084,
-			"tag": "0003_petite_wrecker",
-			"breakpoints": true
-		},
-		{
-			"idx": 4,
-			"version": "7",
-			"when": 1752606108876,
-			"tag": "0004_sleepy_paper_doll",
-			"breakpoints": true
-		},
-		{
-			"idx": 5,
-			"version": "7",
-			"when": 1752606327253,
-			"tag": "0005_chunky_sue_storm",
-			"breakpoints": true
-		},
-		{
-			"idx": 6,
-			"version": "7",
-			"when": 1753112018514,
-			"tag": "0006_majestic_caretaker",
-			"breakpoints": true
-		},
-		{
-			"idx": 7,
-			"version": "7",
-			"when": 1753190159356,
-			"tag": "0007_handy_archangel",
-			"breakpoints": true
-		},
-		{
-			"idx": 8,
-			"version": "7",
-			"when": 1753370737317,
-			"tag": "0008_eminent_the_spike",
-			"breakpoints": true
-		},
-		{
-			"idx": 9,
-			"version": "7",
-			"when": 1754337938241,
-			"tag": "0009_late_lenny_balinger",
-			"breakpoints": true
-		},
-		{
-			"idx": 10,
-			"version": "7",
-			"when": 1754420780849,
-			"tag": "0010_perpetual_lightspeed",
-			"breakpoints": true
-		},
-		{
-			"idx": 11,
-			"version": "7",
-			"when": 1754422064158,
-			"tag": "0011_tan_blackheart",
-			"breakpoints": true
-		},
-		{
-			"idx": 12,
-			"version": "7",
-			"when": 1754476962901,
-			"tag": "0012_warm_the_stranger",
-			"breakpoints": true
-		},
-		{
-			"idx": 13,
-			"version": "7",
-			"when": 1754659373517,
-			"tag": "0013_classy_talkback",
-			"breakpoints": true
-		},
-		{
-			"idx": 14,
-			"version": "7",
-			"when": 1754831765718,
-			"tag": "0014_foamy_vapor",
-			"breakpoints": true
-		},
-		{
-			"idx": 15,
-			"version": "7",
-			"when": 1755443936046,
-			"tag": "0015_wakeful_norman_osborn",
-			"breakpoints": true
-		},
-		{
-			"idx": 16,
-			"version": "7",
-			"when": 1755780572342,
-			"tag": "0016_lonely_mariko_yashida",
-			"breakpoints": true
-		},
-		{
-			"idx": 17,
-			"version": "7",
-			"when": 1755961566627,
-			"tag": "0017_tranquil_shooting_star",
-			"breakpoints": true
-		}
-	]
-}
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1752225352591,
+      "tag": "0000_amusing_namora",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1752326803882,
+      "tag": "0001_odd_night_thrasher",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1752332648392,
+      "tag": "0002_lethal_quentin_quire",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1752332967084,
+      "tag": "0003_petite_wrecker",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1752606108876,
+      "tag": "0004_sleepy_paper_doll",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1752606327253,
+      "tag": "0005_chunky_sue_storm",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1753112018514,
+      "tag": "0006_majestic_caretaker",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1753190159356,
+      "tag": "0007_handy_archangel",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1753370737317,
+      "tag": "0008_eminent_the_spike",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1754337938241,
+      "tag": "0009_late_lenny_balinger",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1754420780849,
+      "tag": "0010_perpetual_lightspeed",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1754422064158,
+      "tag": "0011_tan_blackheart",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1754476962901,
+      "tag": "0012_warm_the_stranger",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1754659373517,
+      "tag": "0013_classy_talkback",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1754831765718,
+      "tag": "0014_foamy_vapor",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1755443936046,
+      "tag": "0015_wakeful_norman_osborn",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1755780572342,
+      "tag": "0016_lonely_mariko_yashida",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1755961566627,
+      "tag": "0017_tranquil_shooting_star",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1756911118035,
+      "tag": "0018_flawless_owl",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1756937533843,
+      "tag": "0019_confused_scream",
+      "breakpoints": true
+    }
+  ]
+}

packages/backend/src/database/schema.ts

@@ -6,3 +6,4 @@ export * from './schema/custodians';
 export * from './schema/ingestion-sources';
 export * from './schema/users';
 export * from './schema/system-settings';
+export * from './schema/api-keys';

packages/backend/src/database/schema/api-keys.ts

@@ -0,0 +1,15 @@
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { users } from './users';
+
+export const apiKeys = pgTable('api_keys', {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: text('name').notNull(),
+    userId: uuid('user_id')
+        .notNull()
+        .references(() => users.id, { onDelete: 'cascade' }),
+    key: text('key').notNull(), // Encrypted API key
+    keyHash: text('key_hash').notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true, mode: 'date' }).notNull(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});

packages/backend/src/index.ts

@@ -17,6 +17,7 @@ import { createDashboardRouter } from './api/routes/dashboard.routes';
 import { createUploadRouter } from './api/routes/upload.routes';
 import { createUserRouter } from './api/routes/user.routes';
 import { createSettingsRouter } from './api/routes/settings.routes';
+import { apiKeyRoutes } from './api/routes/api-key.routes';
 import { AuthService } from './services/AuthService';
 import { UserService } from './services/UserService';
 import { IamService } from './services/IamService';
@@ -28,6 +29,7 @@ import FsBackend from 'i18next-fs-backend';
 import i18nextMiddleware from 'i18next-http-middleware';
 import path from 'path';
 import { logger } from './config/logger';
+import { rateLimiter } from './api/middleware/rateLimiter';
 
 // Load environment variables
 dotenv.config();
@@ -43,7 +45,7 @@ if (!PORT_BACKEND || !JWT_SECRET || !JWT_EXPIRES_IN) {
 
 // --- i18next Initialization ---
 const initializeI18next = async () => {
-	const systemSettings = await settingsService.getSettings();
+	const systemSettings = await settingsService.getSystemSettings();
 	const defaultLanguage = systemSettings?.language || 'en';
 	logger.info({ language: defaultLanguage }, 'Default language');
 	await i18next.use(FsBackend).init({
@@ -86,10 +88,12 @@ const iamRouter = createIamRouter(iamController, authService);
 const uploadRouter = createUploadRouter(authService);
 const userRouter = createUserRouter(authService);
 const settingsRouter = createSettingsRouter(authService);
+const apiKeyRouter = apiKeyRoutes(authService);
 // upload route is added before middleware because it doesn't use the json middleware.
 app.use('/v1/upload', uploadRouter);
 
 // Middleware for all other routes
+app.use(rateLimiter);
 app.use(express.json());
 app.use(express.urlencoded({ extended: true }));
 
@@ -105,6 +109,7 @@ app.use('/v1/search', searchRouter);
 app.use('/v1/dashboard', dashboardRouter);
 app.use('/v1/users', userRouter);
 app.use('/v1/settings', settingsRouter);
+app.use('/v1/api-keys', apiKeyRouter);
 
 // Example of a protected route
 app.get('/v1/protected', requireAuth(authService), (req, res) => {

packages/backend/src/locales/en/translation.json

@@ -58,5 +58,12 @@
 		"invalidFilePath": "Invalid file path",
 		"fileNotFound": "File not found",
 		"downloadError": "Error downloading file"
+	},
+	"apiKeys": {
+		"generateSuccess": "API key generated successfully.",
+		"deleteSuccess": "API key deleted successfully."
+	},
+	"api": {
+		"requestBodyInvalid": "Invalid request body."
 	}
 }

packages/backend/src/services/ApiKeyService.ts

@@ -0,0 +1,72 @@
+import { randomBytes, createHash } from 'crypto';
+import { db } from '../database';
+import { apiKeys } from '../database/schema/api-keys';
+import { CryptoService } from './CryptoService';
+import { and, eq } from 'drizzle-orm';
+import { ApiKey } from '@open-archiver/types';
+
+export class ApiKeyService {
+    public static async generate(
+        userId: string,
+        name: string,
+        expiresInDays: number
+    ): Promise<string> {
+        const key = randomBytes(32).toString('hex');
+        const expiresAt = new Date();
+        expiresAt.setDate(expiresAt.getDate() + expiresInDays);
+        const keyHash = createHash('sha256').update(key).digest('hex');
+
+        await db.insert(apiKeys).values({
+            userId,
+            name,
+            key: CryptoService.encrypt(key),
+            keyHash,
+            expiresAt
+        });
+
+        return key;
+    }
+
+    public static async getKeys(userId: string): Promise<ApiKey[]> {
+        const keys = await db.select().from(apiKeys).where(eq(apiKeys.userId, userId));
+
+        return keys
+            .map((apiKey) => {
+                const decryptedKey = CryptoService.decrypt(apiKey.key);
+                if (!decryptedKey) {
+                    return null;
+                }
+                return {
+                    ...apiKey,
+                    key: decryptedKey.slice(0, 5) + "*****",
+                    expiresAt: apiKey.expiresAt.toISOString(),
+                    createdAt: apiKey.createdAt.toISOString()
+                };
+            })
+            .filter((k): k is NonNullable<typeof k> => k !== null);
+    }
+
+    public static async deleteKey(id: string, userId: string) {
+        await db.delete(apiKeys).where(and(eq(apiKeys.id, id), eq(apiKeys.userId, userId)));
+    }
+    /**
+     * 
+     * @param key API key
+     * @returns The owner user ID or null. null means the API key is not found.
+     */
+    public static async validateKey(key: string): Promise<string | null> {
+        const keyHash = createHash('sha256').update(key).digest('hex');
+        const [apiKey] = await db.select().from(apiKeys).where(eq(apiKeys.keyHash, keyHash));
+        if (!apiKey || apiKey.expiresAt < new Date()) {
+            return null;
+        }
+
+        const decryptedKey = CryptoService.decrypt(apiKey.key);
+        if (decryptedKey !== key) {
+            // This should not happen if the hash matches, but as a security measure, we double-check.
+            return null;
+        }
+
+        return apiKey.userId;
+    }
+}

packages/backend/src/services/SettingsService.ts

@@ -15,11 +15,11 @@ export class SettingsService {
 	 * If no settings exist, it initializes and returns the default settings.
 	 * @returns The system settings.
 	 */
-	public async getSettings(): Promise<SystemSettings> {
+	public async getSystemSettings(): Promise<SystemSettings> {
 		const settings = await db.select().from(systemSettings).limit(1);
 
 		if (settings.length === 0) {
-			return this.createDefaultSettings();
+			return this.createDefaultSystemSettings();
 		}
 
 		return settings[0].config;
@@ -30,8 +30,8 @@ export class SettingsService {
 	 * @param newConfig - A partial object of the new settings configuration.
 	 * @returns The updated system settings.
 	 */
-	public async updateSettings(newConfig: Partial<SystemSettings>): Promise<SystemSettings> {
-		const currentConfig = await this.getSettings();
+	public async updateSystemSettings(newConfig: Partial<SystemSettings>): Promise<SystemSettings> {
+		const currentConfig = await this.getSystemSettings();
 		const mergedConfig = { ...currentConfig, ...newConfig };
 
 		// Since getSettings ensures a record always exists, we can directly update.
@@ -45,7 +45,7 @@ export class SettingsService {
 	 * This is called internally when no settings are found.
 	 * @returns The newly created default settings.
 	 */
-	private async createDefaultSettings(): Promise<SystemSettings> {
+	private async createDefaultSystemSettings(): Promise<SystemSettings> {
 		const [result] = await db
 			.insert(systemSettings)
 			.values({ config: DEFAULT_SETTINGS })

packages/frontend/src/lib/translations/en.json

@@ -222,8 +222,36 @@
 			"system": "System",
 			"users": "Users",
 			"roles": "Roles",
+			"api_keys": "API Keys",
 			"logout": "Logout"
 		},
+		"api_keys_page": {
+			"title": "API Keys",
+			"header": "API Keys",
+			"generate_new_key": "Generate New Key",
+			"name": "Name",
+			"key": "Key",
+			"expires_at": "Expires At",
+			"created_at": "Created At",
+			"actions": "Actions",
+			"delete": "Delete",
+			"no_keys_found": "No API keys found.",
+			"generate_modal_title": "Generate New API Key",
+			"generate_modal_description": "Please provide a name and expiration for your new API key.",
+			"expires_in": "Expires In",
+			"select_expiration": "Select an expiration",
+			"30_days": "30 Days",
+			"60_days": "60 Days",
+			"6_months": "6 Months",
+			"12_months": "12 Months",
+			"24_months": "24 Months",
+			"generate": "Generate",
+			"new_api_key": "New API Key",
+			"failed_to_delete": "Failed to delete API key",
+			"api_key_deleted": "API key deleted",
+			"generated_title": "API Key Generated",
+			"generated_message": "Your API key is generated, please copy and save it in a secure place. This key will only be shown once."
+		},
 		"archived_emails_page": {
 			"title": "Archived emails",
 			"header": "Archived Emails",

packages/frontend/src/routes/dashboard/+layout.svelte

@@ -33,6 +33,10 @@
 					href: '/dashboard/settings/roles',
 					label: $t('app.layout.roles'),
 				},
+				{
+					href: '/dashboard/settings/api-keys',
+					label: $t('app.layout.api_keys'),
+				},
 			],
 		},
 	];

packages/frontend/src/routes/dashboard/settings/api-keys/+page.server.ts

@@ -0,0 +1,50 @@
+import { api } from '$lib/server/api';
+import type { Actions, PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async (event) => {
+    const response = await api('/api-keys', event);
+    const apiKeys = await response.json();
+
+    return {
+        apiKeys,
+    };
+};
+
+export const actions: Actions = {
+    generate: async (event) => {
+        const data = await event.request.formData();
+        const name = data.get('name') as string;
+        const expiresInDays = Number(data.get('expiresInDays'));
+
+        const response = await api('/api-keys', event, {
+            method: 'POST',
+            body: JSON.stringify({ name, expiresInDays }),
+        });
+
+        const responseBody = await response.json();
+
+        if (!response.ok) {
+            return {
+                message: responseBody.message || '',
+                errors: responseBody.errors
+            }
+        }
+
+
+        return {
+            newApiKey: responseBody.key,
+        };
+    },
+    delete: async (event) => {
+        const data = await event.request.formData();
+        const id = data.get('id') as string;
+
+        await api(`/api-keys/${id}`, event, {
+            method: 'DELETE',
+        });
+
+        return {
+            success: true,
+        };
+    },
+};

packages/frontend/src/routes/dashboard/settings/api-keys/+page.svelte

@@ -0,0 +1,266 @@
+<script lang="ts">
+	import { Button } from '$lib/components/ui/button';
+	import * as Dialog from '$lib/components/ui/dialog';
+	import { Input } from '$lib/components/ui/input';
+	import { Label } from '$lib/components/ui/label';
+	import * as Select from '$lib/components/ui/select';
+	import * as Table from '$lib/components/ui/table';
+	import type { ActionData, PageData } from './$types';
+	import { t } from '$lib/translations';
+	import { MoreHorizontal, Trash } from 'lucide-svelte';
+	import * as DropdownMenu from '$lib/components/ui/dropdown-menu';
+	import { setAlert } from '$lib/components/custom/alert/alert-state.svelte';
+	import * as Card from '$lib/components/ui/card/index.js';
+	import { api } from '$lib/api.client';
+
+	// Temporary type definition based on the backend schema
+	type ApiKey = {
+		id: string;
+		name: string;
+		userId: string;
+		key: string;
+		expiresAt: Date;
+		createdAt: Date;
+		updatedAt: Date;
+	};
+
+	let { data, form }: { data: PageData; form: ActionData } = $props();
+	let apiKeys = $state<ApiKey[]>(data.apiKeys);
+
+	let isDeleteDialogOpen = $state(false);
+	let newAPIKeyDialogOpen = $state(false);
+	let keyToDelete = $state<ApiKey | null>(null);
+	let isDeleting = $state(false);
+	let selectedExpiration = $state('30');
+	const expirationOptions = [
+		{ value: '30', label: $t('app.api_keys_page.30_days') },
+		{ value: '60', label: $t('app.api_keys_page.60_days') },
+		{ value: '180', label: $t('app.api_keys_page.6_months') },
+		{ value: '365', label: $t('app.api_keys_page.12_months') },
+		{ value: '730', label: $t('app.api_keys_page.24_months') },
+	];
+	const triggerContent = $derived(
+		expirationOptions.find((p) => p.value === selectedExpiration)?.label ??
+			$t('app.api_keys_page.select_expiration')
+	);
+
+	const openDeleteDialog = (apiKey: ApiKey) => {
+		keyToDelete = apiKey;
+		isDeleteDialogOpen = true;
+	};
+
+	const confirmDelete = async () => {
+		if (!keyToDelete) return;
+		isDeleting = true;
+		try {
+			const res = await api(`/api-keys/${keyToDelete.id}`, { method: 'DELETE' });
+			if (!res.ok) {
+				const errorBody = await res.json();
+				setAlert({
+					type: 'error',
+					title: $t('app.api_keys_page.failed_to_delete'),
+					message: errorBody.message || JSON.stringify(errorBody),
+					duration: 5000,
+					show: true,
+				});
+				return;
+			}
+			apiKeys = apiKeys.filter((k) => k.id !== keyToDelete!.id);
+			isDeleteDialogOpen = false;
+			keyToDelete = null;
+			setAlert({
+				type: 'success',
+				title: $t('app.api_keys_page.api_key_deleted'),
+				message: $t('app.api_keys_page.api_key_deleted'),
+				duration: 3000,
+				show: true,
+			});
+		} finally {
+			isDeleting = false;
+		}
+	};
+
+	$effect(() => {
+		if (form?.newApiKey) {
+			setAlert({
+				type: 'success',
+				title: $t('app.api_keys_page.generated_title'),
+				message: $t('app.api_keys_page.generated_message'),
+				duration: 3000, // Keep it on screen longer for copying
+				show: true,
+			});
+		}
+		if (form?.errors) {
+			setAlert({
+				type: 'error',
+				title: form.message,
+				message: form.errors || '',
+				duration: 3000, // Keep it on screen longer for copying
+				show: true,
+			});
+		}
+	});
+</script>
+
+<svelte:head>
+	<title>{$t('app.api_keys_page.title')} - Open Archiver</title>
+</svelte:head>
+
+<div class="">
+	<div class="mb-4 flex items-center justify-between">
+		<h1 class="text-2xl font-bold">{$t('app.api_keys_page.title')}</h1>
+		<Dialog.Root bind:open={newAPIKeyDialogOpen}>
+			<Dialog.Trigger>
+				<Button>{$t('app.api_keys_page.generate_new_key')}</Button>
+			</Dialog.Trigger>
+			<Dialog.Content>
+				<Dialog.Header>
+					<Dialog.Title>{$t('app.api_keys_page.generate_modal_title')}</Dialog.Title>
+					<Dialog.Description>
+						{$t('app.api_keys_page.generate_modal_description')}
+					</Dialog.Description>
+				</Dialog.Header>
+				<form
+					method="POST"
+					action="?/generate"
+					onsubmit={() => {
+						newAPIKeyDialogOpen = false;
+					}}
+				>
+					<div class="grid gap-4 py-4">
+						<div class="grid grid-cols-4 items-center gap-4">
+							<Label for="name" class="text-right"
+								>{$t('app.api_keys_page.name')}</Label
+							>
+							<Input id="name" name="name" class="col-span-3" />
+						</div>
+						<div class="grid grid-cols-4 items-center gap-4">
+							<Label for="expiresInDays" class="text-right"
+								>{$t('app.api_keys_page.expires_in')}</Label
+							>
+							<Select.Root
+								name="expiresInDays"
+								bind:value={selectedExpiration}
+								type="single"
+							>
+								<Select.Trigger class="col-span-3">
+									{triggerContent}
+								</Select.Trigger>
+								<Select.Content>
+									{#each expirationOptions as option}
+										<Select.Item value={option.value}
+											>{option.label}</Select.Item
+										>
+									{/each}
+								</Select.Content>
+							</Select.Root>
+						</div>
+					</div>
+					<Dialog.Footer>
+						<Button type="submit">{$t('app.api_keys_page.generate')}</Button>
+					</Dialog.Footer>
+				</form>
+			</Dialog.Content>
+		</Dialog.Root>
+	</div>
+	{#if form?.newApiKey}
+		<Card.Root class="mb-4 border-0 bg-green-200 text-green-600 shadow-none">
+			<Card.Header>
+				<Card.Title>{$t('app.api_keys_page.generated_title')}</Card.Title>
+				<Card.Description class=" text-green-600"
+					>{$t('app.api_keys_page.generated_message')}</Card.Description
+				>
+			</Card.Header>
+			<Card.Content>
+				<p>{form?.newApiKey}</p>
+			</Card.Content>
+		</Card.Root>
+	{/if}
+
+	<div class="rounded-md border">
+		<Table.Root>
+			<Table.Header>
+				<Table.Row>
+					<Table.Head>{$t('app.api_keys_page.name')}</Table.Head>
+					<Table.Head>{$t('app.api_keys_page.key')}</Table.Head>
+					<Table.Head>{$t('app.api_keys_page.expires_at')}</Table.Head>
+					<Table.Head>{$t('app.api_keys_page.created_at')}</Table.Head>
+					<Table.Head class="text-right">{$t('app.users.actions')}</Table.Head>
+				</Table.Row>
+			</Table.Header>
+			<Table.Body>
+				{#if apiKeys.length > 0}
+					{#each apiKeys as apiKey (apiKey.id)}
+						<Table.Row>
+							<Table.Cell>{apiKey.name}</Table.Cell>
+							<Table.Cell>{apiKey.key.substring(0, 8)}</Table.Cell>
+							<Table.Cell
+								>{new Date(apiKey.expiresAt).toLocaleDateString()}</Table.Cell
+							>
+							<Table.Cell
+								>{new Date(apiKey.createdAt).toLocaleDateString()}</Table.Cell
+							>
+							<Table.Cell class="text-right">
+								<DropdownMenu.Root>
+									<DropdownMenu.Trigger>
+										<Button variant="ghost" class="h-8 w-8 p-0">
+											<span class="sr-only">{$t('app.users.open_menu')}</span>
+											<MoreHorizontal class="h-4 w-4" />
+										</Button>
+									</DropdownMenu.Trigger>
+									<DropdownMenu.Content>
+										<DropdownMenu.Label
+											>{$t('app.users.actions')}</DropdownMenu.Label
+										>
+										<DropdownMenu.Separator />
+										<DropdownMenu.Item
+											class="text-destructive cursor-pointer"
+											onclick={() => openDeleteDialog(apiKey)}
+										>
+											<Trash class="mr-2 h-4 w-4" />
+											{$t('app.users.delete')}
+										</DropdownMenu.Item>
+									</DropdownMenu.Content>
+								</DropdownMenu.Root>
+							</Table.Cell>
+						</Table.Row>
+					{/each}
+				{:else}
+					<Table.Row>
+						<Table.Cell colspan={5} class="h-24 text-center"
+							>{$t('app.api_keys_page.no_keys_found')}</Table.Cell
+						>
+					</Table.Row>
+				{/if}
+			</Table.Body>
+		</Table.Root>
+	</div>
+</div>
+
+<Dialog.Root bind:open={isDeleteDialogOpen}>
+	<Dialog.Content class="sm:max-w-lg">
+		<Dialog.Header>
+			<Dialog.Title>{$t('app.users.delete_confirmation_title')}</Dialog.Title>
+			<Dialog.Description>
+				{$t('app.users.delete_confirmation_description')}
+			</Dialog.Description>
+		</Dialog.Header>
+		<Dialog.Footer class="sm:justify-start">
+			<Button
+				type="button"
+				variant="destructive"
+				onclick={confirmDelete}
+				disabled={isDeleting}
+			>
+				{#if isDeleting}
+					{$t('app.users.deleting')}...
+				{:else}
+					{$t('app.users.confirm')}
+				{/if}
+			</Button>
+			<Dialog.Close>
+				<Button type="button" variant="secondary">{$t('app.users.cancel')}</Button>
+			</Dialog.Close>
+		</Dialog.Footer>
+	</Dialog.Content>
+</Dialog.Root>

packages/frontend/src/routes/dashboard/settings/system/+page.server.ts

@@ -4,7 +4,7 @@ import { error, fail } from '@sveltejs/kit';
 import type { Actions, PageServerLoad } from './$types';
 
 export const load: PageServerLoad = async (event) => {
-	const response = await api('/settings', event);
+	const response = await api('/settings/system', event);
 
 	if (!response.ok) {
 		const { message } = await response.json();
@@ -30,7 +30,7 @@ export const actions: Actions = {
 			supportEmail: supportEmail ? String(supportEmail) : null,
 		};
 
-		const response = await api('/settings', event, {
+		const response = await api('/settings/system', event, {
 			method: 'PUT',
 			body: JSON.stringify(body),
 		});

packages/types/src/user.types.ts

@@ -35,3 +35,11 @@ export interface Role {
 	createdAt: Date;
 	updatedAt: Date;
 }
+
+export interface ApiKey {
+	id: string;
+	name: string;
+	key: string;
+	expiresAt: string;
+	createdAt: string;
+}

pnpm-lock.yaml

@@ -156,6 +156,9 @@ importers:
       yauzl:
         specifier: ^3.2.0
         version: 3.2.0
+      zod:
+        specifier: ^4.1.5
+        version: 4.1.5
     devDependencies:
       '@bull-board/api':
         specifier: ^6.11.0
@@ -4801,6 +4804,9 @@ packages:
     resolution: {integrity: sha512-zK7YHHz4ZXpW89AHXUPbQVGKI7uvkd3hzusTdotCg1UxyaVtg0zFJSTfW/Dq5f7OBBVnq6cZIaC8Ti4hb6dtCA==}
     engines: {node: '>= 14'}
 
+  zod@4.1.5:
+    resolution: {integrity: sha512-rcUUZqlLJgBC33IT3PNMgsCq6TzLQEG/Ei/KTCU0PedSWRMAXoOUN+4t/0H+Q8bdnLPdqUYnvboJT0bn/229qg==}
+
   zwitch@2.0.4:
     resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
 
@@ -9765,4 +9771,6 @@ snapshots:
       compress-commons: 6.0.2
       readable-stream: 4.7.0
 
+  zod@4.1.5: {}
+
   zwitch@2.0.4: {}