@delmaredigital/payload-better-auth 0.4.0 → 0.4.1

package/README.md

@@ -494,6 +494,27 @@ API keys can have granular permission scopes. By default, scopes are auto-genera
 | `includeCollectionScopes` | `boolean` | `true` when no custom scopes, `false` when custom scopes provided | Include auto-generated collection scopes |
 | `excludeCollections` | `string[]` | `['sessions', 'verifications', 'accounts', 'twoFactors', 'apikeys']` | Collections to exclude from auto-generated scopes |
 | `defaultScopes` | `string[]` | `[]` | Default scopes pre-selected when creating a key |
+| `requiredRole` | `string \| string[] \| null` | Inherits from `admin.login.requiredRole` or `'admin'` | Role(s) required to create/update/delete API keys. Set to `null` to allow any authenticated user (not recommended) |
+
+**Restricting API key management to admins:**
+
+If your `admin.login.requiredRole` includes non-admin roles (e.g., editors who need admin panel access but shouldn't manage API keys), set `requiredRole` explicitly:
+
+```typescript
+createBetterAuthPlugin({
+  createAuth,
+  admin: {
+    login: {
+      requiredRole: ['admin', 'content_editor'], // both can access admin panel
+    },
+    apiKey: {
+      requiredRole: 'admin', // only admins can create/update/delete API keys
+    },
+  },
+})
+```
+
+> **Note:** API key **verification** is not affected by this setting — existing keys continue to work regardless of who created them. This only restricts key management (create, update, delete).
 
 **Zero Config (recommended):**
 ```typescript

package/dist/plugin/index.js

@@ -5,6 +5,7 @@
  */ import { detectAuthConfig } from '../utils/detectAuthConfig.js';
 import { detectEnabledPlugins } from '../utils/detectEnabledPlugins.js';
 import { buildAvailableScopes, scopesToPermissions } from '../utils/generateScopes.js';
+import { hasAnyRole, normalizeRoles } from '../utils/access.js';
 // Track auth instance for HMR
 let authInstance = null;
 // Store API key scopes config for access by management views
@@ -115,7 +116,7 @@ let apiKeyScopesConfig = undefined;
 }
 /**
  * Creates the auth endpoint handler that proxies requests to Better Auth.
- */ function createAuthEndpointHandler() {
+ */ function createAuthEndpointHandler(adminOptions) {
     return async (req)=>{
         const payloadWithAuth = req.payload;
         const auth = payloadWithAuth.betterAuth;
@@ -170,6 +171,45 @@ let apiKeyScopesConfig = undefined;
                     }
                 }
             }
+            // Guard API key mutation endpoints — require admin role
+            const isApiKeyMutation = req.method === 'POST' && (pathname.endsWith('/api-key/create') || pathname.endsWith('/api-key/update') || pathname.endsWith('/api-key/delete'));
+            if (isApiKeyMutation) {
+                const session = await auth.api.getSession({
+                    headers: req.headers
+                });
+                if (!session?.user?.id) {
+                    return new Response(JSON.stringify({
+                        error: 'Unauthorized'
+                    }), {
+                        status: 401,
+                        headers: {
+                            'Content-Type': 'application/json'
+                        }
+                    });
+                }
+                // Resolve required role: apiKey config > login config > default 'admin'
+                const requiredRole = apiKeyScopesConfig?.requiredRole ?? adminOptions?.login?.requiredRole ?? 'admin';
+                if (requiredRole !== null) {
+                    // Find the auth collection slug from Payload's config
+                    const authSlug = req.payload.config.collections.find((c)=>typeof c.auth === 'object' || c.auth === true)?.slug ?? 'users';
+                    const user = await req.payload.findByID({
+                        collection: authSlug,
+                        id: session.user.id,
+                        depth: 0,
+                        overrideAccess: true
+                    });
+                    if (!hasAnyRole(user, normalizeRoles(requiredRole))) {
+                        return new Response(JSON.stringify({
+                            error: 'Forbidden: insufficient permissions to manage API keys'
+                        }), {
+                            status: 403,
+                            headers: {
+                                'Content-Type': 'application/json'
+                            }
+                        });
+                    }
+                }
+            }
             // Intercept API key creation requests with scopes
             // Better Auth's API key create endpoint is POST /api-key/create
             const isApiKeyCreate = req.method === 'POST' && pathname.endsWith('/api-key/create') && parsedBody?.scopes && Array.isArray(parsedBody.scopes);
@@ -199,8 +239,8 @@ let apiKeyScopesConfig = undefined;
 }
 /**
  * Generates Payload endpoints for Better Auth.
- */ function generateAuthEndpoints(basePath) {
-    const handler = createAuthEndpointHandler();
+ */ function generateAuthEndpoints(basePath, adminOptions) {
+    const handler = createAuthEndpointHandler(adminOptions);
     const methods = [
         'get',
         'post',
@@ -384,7 +424,7 @@ let apiKeyScopesConfig = undefined;
         // Inject management UI components
         config = injectManagementComponents(config, options);
         // Generate auth endpoints if enabled
-        const authEndpoints = autoRegisterEndpoints ? generateAuthEndpoints(authBasePath) : [];
+        const authEndpoints = autoRegisterEndpoints ? generateAuthEndpoints(authBasePath, options.admin) : [];
         // Merge endpoints
         const existingEndpoints = config.endpoints ?? [];
         // Get existing onInit

package/dist/types/apiKey.d.ts

@@ -50,6 +50,14 @@ export type ApiKeyScopesConfig = {
      * If not provided, keys without scopes will have no permissions.
      */
     defaultScopes?: string[];
+    /**
+     * Role(s) required to create, update, and delete API keys.
+     * - string: Single role required (e.g., 'admin')
+     * - string[]: Any matching role grants access
+     * - null: Allow any authenticated user (not recommended)
+     * @default Inherits from admin.login.requiredRole, or 'admin' if unset
+     */
+    requiredRole?: string | string[] | null;
 };
 /**
  * Scope data passed to the API keys management client component.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-better-auth",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Better Auth adapter and plugins for Payload CMS",
   "type": "module",
   "license": "MIT",