api key support

[Dasa122]

[coderabbitai]

Coding Plan

Summary

• Leverage the @better-auth/api-key plugin which handles key hashing, storage, and automatic session mocking for API key-authenticated requests
• The existing auth middleware requires no changes since better-auth's getSession() automatically returns mock sessions for valid API keys
• Create dedicated CRUD routes for API key management to maintain consistency with existing codebase patterns
• Build a self-service admin UI where authenticated users can create, view, and revoke their own API keys

Implementation Steps

Phase 1: Backend API Key Plugin Integration

Configure the better-auth API key plugin to enable API key authentication. The plugin handles database schema creation, key hashing, and session mocking automatically.

Task 1: Install API Key Plugin Package

Add the @better-auth/api-key package to the chronos application.

• Add @better-auth/api-key to dependencies in apps/chronos/package.json
• Run package installation to update lockfile

Task 2: Configure API Key Plugin in Better-Auth

Integrate the apiKey plugin into the existing better-auth configuration to enable API key authentication.

• Update apps/chronos/src/utils/authentication.ts to import and add the apiKey plugin from @better-auth/api-key
• Configure the plugin with enableSessionForAPIKeys: true to automatically create mock sessions when requests include valid API keys in the x-api-key header
• The plugin will automatically create the required apikey table via better-auth's schema management
• No changes needed to authenticationMiddleware — the existing auth.api.getSession() call will automatically return a mocked session for valid API key requests

🤖 Prompt for AI agents

Set up the `@better-auth/api-key` plugin in the chronos backend to enable API
key authentication. The goal is to integrate the plugin into the existing
better-auth configuration with minimal changes to the rest of the codebase.

- Add `@better-auth/api-key` as a dependency in `apps/chronos/package.json` and
run the package installer to update the lockfile
- In `apps/chronos/src/utils/authentication.ts`, import the `apiKey` plugin from
`@better-auth/api-key` and add it to the plugins array of the better-auth
configuration
- Configure the plugin with `enableSessionForAPIKeys: true` so that requests
including a valid API key in the `x-api-key` header automatically receive a
mocked session from `auth.api.getSession()`
- No changes are required to `authenticationMiddleware` or any other middleware
— the existing session retrieval logic handles API key requests transparently
once the plugin is configured
- The plugin will automatically manage the required `apikey` database table via
better-auth's schema management

Phase 2: API Key Management Routes

Create dedicated routes for users to manage their API keys. While better-auth provides some built-in endpoints, custom routes ensure consistent patterns with the existing codebase and provide full CRUD control.

Task 1: Create API Key Route Structure

Set up the route files following the established factory/router pattern.

• Create apps/chronos/src/routes/api-keys/_factory.ts with createFactory<Context>()
• Create apps/chronos/src/routes/api-keys/_router.ts to mount handler arrays at HTTP methods/paths
• Create apps/chronos/src/routes/api-keys/index.ts for handler implementations

Task 2: Implement API Key CRUD Handlers

Build handlers for listing, creating, and revoking API keys scoped to the authenticated user.

• Implement listApiKeys handler (GET /) that returns all API keys owned by the current user (excluding the actual key value, only metadata)
• Implement createApiKey handler (POST /) that creates a new API key for the current user, accepting a name/label, and returning the full key value only once at creation time
• Implement deleteApiKey handler (DELETE /:id) that revokes an API key owned by the current user
• All handlers should use requireAuthentication middleware
• Add Zod validation schemas for request/response payloads
• Add OpenAPI documentation via describeRoute()

Task 3: Register Routes and Export Types

Wire up the new router to the application and make types available for the frontend client.

• Mount the router in apps/chronos/src/index.ts with api.route('/api-keys', apiKeysRouter)
• Export ApiKeysRouter type in apps/chronos/src/_types/hc.ts

🤖 Prompt for AI agents

Create the API key management routes in the chronos backend following the
established factory/router pattern. The goal is to expose CRUD endpoints for API
key management scoped to the authenticated user.

**Create route files:**
- `apps/chronos/src/routes/api-keys/_factory.ts` — initialize with
`createFactory<Context>()`
- `apps/chronos/src/routes/api-keys/_router.ts` — mount handler arrays at the
appropriate HTTP methods and paths
- `apps/chronos/src/routes/api-keys/index.ts` — implement all handler logic

**Implement handlers in `index.ts`:**
- `listApiKeys` (GET `/`) — return all API keys owned by the current
authenticated user, including only metadata (no raw key values)
- `createApiKey` (POST `/`) — accept a name/label, create a new API key for the
current user, and return the full key value only once at creation time
- `deleteApiKey` (DELETE `/:id`) — revoke a specific API key owned by the
current user
- All handlers must use `requireAuthentication` middleware
- Add Zod validation schemas for all request and response payloads
- Add OpenAPI documentation for each route via `describeRoute()`

**Wire up the router:**
- In `apps/chronos/src/index.ts`, mount the router with `api.route('/api-keys',
apiKeysRouter)`
- Export the `ApiKeysRouter` type in `apps/chronos/src/_types/hc.ts` for
frontend client use

Phase 3: Frontend API Key Management UI

Create an admin interface for users to view and manage their API keys, following existing patterns from the users/roles management pages.

Task 1: Add Client Plugin and API Client

Configure the frontend to support API key management via the typed client.

• Add @better-auth/api-key to dependencies in apps/iris/package.json (for client types)
• Add the apiKeyClient plugin to authClient in apps/iris/src/utils/authentication.ts
• Add apiKeys entry to apps/iris/src/utils/hc.ts pointing to the new chronos router
• Add query keys for API keys in apps/iris/src/utils/query-keys.ts

Task 2: Create API Keys Admin Page

Build the main page for viewing and managing API keys.

• Create apps/iris/src/routes/_private/admin/api-keys.tsx as a new file-based route
• Implement the page with TanStack Query to fetch the user's API keys via the typed client
• Include a "Create API Key" button that opens a dialog
• Display API keys in a table showing name, creation date, and a delete action
• Follow the existing patterns from users.tsx and roles.tsx for layout and state management

Task 3: Create API Key Table Component

Build a reusable table component for displaying API keys.

• Create apps/iris/src/components/admin/api-keys-table.tsx
• Display columns: name, created date, last used (if available), actions
• Include delete button per row with confirmation
• Follow patterns from users-table.tsx and roles-table.tsx

Task 4: Create API Key Dialog Component

Build a dialog for creating new API keys and displaying the generated key.

• Create apps/iris/src/components/admin/api-key-dialog.tsx
• Implement create mode with a name/label input field
• On successful creation, display the generated API key with a copy-to-clipboard button and a warning that it won't be shown again
• Use TanStack Form for field management and TanStack Query mutations for the API call
• Follow patterns from role-dialog.tsx for dialog structure

Task 5: Add API Keys to Admin Sidebar

Make the API keys page accessible from the admin navigation.

• Update apps/iris/src/components/admin/sidebar.tsx to add an API Keys menu item
• Place it in the management category alongside Users and Roles
• Use an appropriate icon from lucide-react (e.g., KeyRound or Key)
• No permission guard needed since users manage their own keys

Task 6: Add Translations

Add i18n translation keys for the API keys UI.

• Add translation entries for API key page title, descriptions, form labels, success/error messages, and table column headers
• Follow the existing translation key patterns in the localization files

🤖 Prompt for AI agents

Build the frontend API key management UI in the iris app, following the
established patterns from the users and roles management pages. The goal is to
give authenticated users a self-service admin interface to create, view, and
revoke their API keys.

**Configure the client (Task 3.1):**
- Add `@better-auth/api-key` to `apps/iris/package.json` for client types
- Add the `apiKeyClient` plugin to `authClient` in
`apps/iris/src/utils/authentication.ts`
- Add an `apiKeys` entry in `apps/iris/src/utils/hc.ts` pointing to the
`ApiKeysRouter` type from chronos
- Add query keys for API keys in `apps/iris/src/utils/query-keys.ts`

**Create the admin page — `apps/iris/src/routes/_private/admin/api-keys.tsx`:**
- Use TanStack Query to fetch the user's API keys via the typed client
- Include a "Create API Key" button that opens the create dialog
- Render the API keys table component
- Follow the layout and state management patterns from `users.tsx` and
`roles.tsx`

**Create the table component —
`apps/iris/src/components/admin/api-keys-table.tsx`:**
- Display columns: name, created date, last used (if available), and actions
- Include a delete button per row with a confirmation step
- Follow patterns from `users-table.tsx` and `roles-table.tsx`

**Create the dialog component —
`apps/iris/src/components/admin/api-key-dialog.tsx`:**
- Implement a create mode with a name/label input field
- After successful creation, display the generated API key with a
copy-to-clipboard button and a warning that the key will not be shown again
- Use TanStack Form for field management and TanStack Query mutations for the
API call
- Follow the dialog structure from `role-dialog.tsx`

**Update the sidebar — `apps/iris/src/components/admin/sidebar.tsx`:**
- Add an API Keys menu item in the management category alongside Users and Roles
- Use the `KeyRound` or `Key` icon from lucide-react
- No permission guard is needed since users manage their own keys

**Add translations:**
- Add i18n entries for the API key page title, descriptions, form labels,
success/error messages, and table column headers
- Follow the existing translation key patterns in the localization files

Research

The platform consists of a Hono-based backend (chronos) and a React frontend (iris). Authentication is handled by better-auth with Microsoft Entra SSO, storing sessions in PostgreSQL via Drizzle ORM. The backend uses a middleware chain where authenticationMiddleware populates user/session context, and requireAuthentication/requireAuthorization enforce access control. Routes follow a factory pattern with _factory.ts, _router.ts, and handler files. The frontend uses TanStack Router/Query with a typed Hono client (hc) for API calls, and admin pages follow a table + dialog pattern with shadcn components.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the `@better-auth/api-key` plugin in the chronos backend to enable API
key authentication. The goal is to integrate the plugin into the existing
better-auth configuration with minimal changes to the rest of the codebase.

- Add `@better-auth/api-key` as a dependency in `apps/chronos/package.json` and
run the package installer to update the lockfile
- In `apps/chronos/src/utils/authentication.ts`, import the `apiKey` plugin from
`@better-auth/api-key` and add it to the plugins array of the better-auth
configuration
- Configure the plugin with `enableSessionForAPIKeys: true` so that requests
including a valid API key in the `x-api-key` header automatically receive a
mocked session from `auth.api.getSession()`
- No changes are required to `authenticationMiddleware` or any other middleware
— the existing session retrieval logic handles API key requests transparently
once the plugin is configured
- The plugin will automatically manage the required `apikey` database table via
better-auth's schema management
===============================================================================

Task: 2

Create the API key management routes in the chronos backend following the
established factory/router pattern. The goal is to expose CRUD endpoints for API
key management scoped to the authenticated user.

**Create route files:**
- `apps/chronos/src/routes/api-keys/_factory.ts` — initialize with
`createFactory<Context>()`
- `apps/chronos/src/routes/api-keys/_router.ts` — mount handler arrays at the
appropriate HTTP methods and paths
- `apps/chronos/src/routes/api-keys/index.ts` — implement all handler logic

**Implement handlers in `index.ts`:**
- `listApiKeys` (GET `/`) — return all API keys owned by the current
authenticated user, including only metadata (no raw key values)
- `createApiKey` (POST `/`) — accept a name/label, create a new API key for the
current user, and return the full key value only once at creation time
- `deleteApiKey` (DELETE `/:id`) — revoke a specific API key owned by the
current user
- All handlers must use `requireAuthentication` middleware
- Add Zod validation schemas for all request and response payloads
- Add OpenAPI documentation for each route via `describeRoute()`

**Wire up the router:**
- In `apps/chronos/src/index.ts`, mount the router with `api.route('/api-keys',
apiKeysRouter)`
- Export the `ApiKeysRouter` type in `apps/chronos/src/_types/hc.ts` for
frontend client use
===============================================================================

Task: 3

Build the frontend API key management UI in the iris app, following the
established patterns from the users and roles management pages. The goal is to
give authenticated users a self-service admin interface to create, view, and
revoke their API keys.

**Configure the client (Task 3.1):**
- Add `@better-auth/api-key` to `apps/iris/package.json` for client types
- Add the `apiKeyClient` plugin to `authClient` in
`apps/iris/src/utils/authentication.ts`
- Add an `apiKeys` entry in `apps/iris/src/utils/hc.ts` pointing to the
`ApiKeysRouter` type from chronos
- Add query keys for API keys in `apps/iris/src/utils/query-keys.ts`

**Create the admin page — `apps/iris/src/routes/_private/admin/api-keys.tsx`:**
- Use TanStack Query to fetch the user's API keys via the typed client
- Include a "Create API Key" button that opens the create dialog
- Render the API keys table component
- Follow the layout and state management patterns from `users.tsx` and
`roles.tsx`

**Create the table component —
`apps/iris/src/components/admin/api-keys-table.tsx`:**
- Display columns: name, created date, last used (if available), and actions
- Include a delete button per row with a confirmation step
- Follow patterns from `users-table.tsx` and `roles-table.tsx`

**Create the dialog component —
`apps/iris/src/components/admin/api-key-dialog.tsx`:**
- Implement a create mode with a name/label input field
- After successful creation, display the generated API key with a
copy-to-clipboard button and a warning that the key will not be shown again
- Use TanStack Form for field management and TanStack Query mutations for the
API call
- Follow the dialog structure from `role-dialog.tsx`

**Update the sidebar — `apps/iris/src/components/admin/sidebar.tsx`:**
- Add an API Keys menu item in the management category alongside Users and Roles
- Use the `KeyRound` or `Key` icon from lucide-react
- No permission guard is needed since users manage their own keys

**Add translations:**
- Add i18n entries for the API key page title, descriptions, form labels,
success/error messages, and table column headers
- Follow the existing translation key patterns in the localization files

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!