@delmaredigital/payload-better-auth 0.5.5 → 0.6.0

package/dist/components/management/views/ApiKeysView.js

@@ -2,8 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DefaultTemplate } from '@payloadcms/next/templates';
 import { getVisibleEntities } from '@payloadcms/ui/shared';
 import { ApiKeysManagementClient } from '../ApiKeysManagementClient.js';
-import { getApiKeyScopesConfig } from '../../../plugin/index.js';
-import { buildAvailableScopes } from '../../../utils/generateScopes.js';
+import { getApiKeyPermissionsConfig } from '../../../plugin/index.js';
+import { generateCollectionPermissions } from '../../../utils/generatePermissions.js';
 /**
  * API Keys management view for Payload admin panel.
  * Server component that provides the admin layout.
@@ -16,11 +16,9 @@ import { buildAvailableScopes } from '../../../utils/generateScopes.js';
     const visibleEntities = getVisibleEntities({
         req
     });
-    // Build available scopes from plugin config and collections
-    const scopesConfig = getApiKeyScopesConfig();
-    const availableScopes = buildAvailableScopes(payload.config.collections, scopesConfig);
-    // Get default scopes from config
-    const defaultScopes = scopesConfig?.defaultScopes ?? [];
+    // Build permission definitions from collections
+    const permissionsConfig = getApiKeyPermissionsConfig();
+    const permissions = generateCollectionPermissions(payload.config.collections, permissionsConfig?.excludeCollections);
     return /*#__PURE__*/ _jsx(DefaultTemplate, {
         i18n: req.i18n,
         locale: req.locale,
@@ -31,8 +29,7 @@ import { buildAvailableScopes } from '../../../utils/generateScopes.js';
         user: req.user ?? undefined,
         visibleEntities: visibleEntities,
         children: /*#__PURE__*/ _jsx(ApiKeysManagementClient, {
-            availableScopes: availableScopes,
-            defaultScopes: defaultScopes
+            permissions: permissions
         })
     });
 }

package/dist/index.d.ts

@@ -10,16 +10,16 @@ export { payloadAdapter, detectDbType, resolveIdType } from './adapter/index.js'
 export type { PayloadAdapterConfig, DbType } from './adapter/index.js';
 export { betterAuthCollections } from './adapter/collections.js';
 export type { BetterAuthCollectionsOptions } from './adapter/collections.js';
-export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyScopesConfig, } from './plugin/index.js';
+export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyPermissionsConfig, } from './plugin/index.js';
 export type { Auth, CreateAuthFunction, BetterAuthPluginOptions, BetterAuthPluginAdminOptions, BetterAuthStrategyOptions, } from './plugin/index.js';
 export type { BetterAuthReturn, PayloadWithAuth, PayloadRequestWithBetterAuth, CollectionHookWithBetterAuth, EndpointWithBetterAuth, RoleArray, } from './types/betterAuth.js';
 export type { User, Session as BetterAuthSession, Account, Verification, Apikey, Passkey, Organization, Member, Invitation, Team, TeamMember, TwoFactor, BaseUserFields, BaseSessionFields, BaseAccountFields, UserPluginFields, SessionPluginFields, BetterAuthFullSchema, ModelKey, PluginId, } from './generated-types.js';
-export type { ScopeDefinition, ApiKeyScopesConfig, AvailableScope, } from './types/apiKey.js';
-export { generateScopesFromCollections, buildAvailableScopes, scopesToPermissions, } from './utils/generateScopes.js';
+export type { PermissionDefinition, ApiKeyPermissionsConfig, } from './types/apiKey.js';
+export { generateCollectionPermissions, } from './utils/generatePermissions.js';
 export { normalizeRoles, hasAnyRole, hasAllRoles, hasAdminRoles, isAdmin, isAdminField, isAdminOrSelf, canUpdateOwnFields, isAuthenticated, isAuthenticatedField, hasRole, hasRoleField, requireAllRoles, } from './utils/access.js';
 export type { RoleCheckConfig, SelfAccessConfig, FieldUpdateConfig, } from './utils/access.js';
-export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAnyScopeKey, hasAllScopes as hasAllScopesKey, requireScope, requireAnyScope, requireAllScopes as requireAllScopesKey, allowSessionOrScope, allowSessionOrAnyScope, validateApiKey, } from './utils/apiKeyAccess.js';
-export type { ApiKeyInfo, ApiKeyAccessConfig, } from './utils/apiKeyAccess.js';
+export { extractApiKeyFromRequest, requirePermission, requireAnyPermission, requireAllPermissions, allowSessionOrPermission, allowSessionOrAnyPermission, requireApiKey, } from './utils/apiKeyAccess.js';
+export type { ApiKeyPermissionConfig, PermissionCheck, } from './utils/apiKeyAccess.js';
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 export type { AuthDetectionResult } from './utils/detectAuthConfig.js';
 export { getServerSession, getServerUser, createSessionHelpers } from './utils/session.js';

package/dist/index.js

@@ -10,13 +10,13 @@ export { payloadAdapter, detectDbType, resolveIdType } from './adapter/index.js'
 // Collection generator plugin
 export { betterAuthCollections } from './adapter/collections.js';
 // Payload plugin and strategy
-export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyScopesConfig } from './plugin/index.js';
-// Scope utilities
-export { generateScopesFromCollections, buildAvailableScopes, scopesToPermissions } from './utils/generateScopes.js';
+export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyPermissionsConfig } from './plugin/index.js';
+// Permission utilities
+export { generateCollectionPermissions } from './utils/generatePermissions.js';
 // Access control utilities
 export { normalizeRoles, hasAnyRole, hasAllRoles, hasAdminRoles, isAdmin, isAdminField, isAdminOrSelf, canUpdateOwnFields, isAuthenticated, isAuthenticatedField, hasRole, hasRoleField, requireAllRoles } from './utils/access.js';
-// API key scope enforcement utilities
-export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAnyScopeKey, hasAllScopes as hasAllScopesKey, requireScope, requireAnyScope, requireAllScopes as requireAllScopesKey, allowSessionOrScope, allowSessionOrAnyScope, validateApiKey } from './utils/apiKeyAccess.js';
+// API key permission enforcement utilities
+export { extractApiKeyFromRequest, requirePermission, requireAnyPermission, requireAllPermissions, allowSessionOrPermission, allowSessionOrAnyPermission, requireApiKey } from './utils/apiKeyAccess.js';
 // Auth config detection utility
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 // Session utilities

package/dist/plugin/index.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Plugin, AuthStrategy, BasePayload } from 'payload';
 import type { betterAuth, BetterAuthOptions } from 'better-auth';
-import type { ApiKeyScopesConfig } from '../types/apiKey.js';
+import type { ApiKeyPermissionsConfig } from '../types/apiKey.js';
 export type Auth = ReturnType<typeof betterAuth>;
 export type { PayloadWithAuth } from '../types/betterAuth.js';
 export type CreateAuthFunction = (payload: BasePayload) => any;
@@ -97,11 +97,11 @@ export type BetterAuthPluginAdminOptions = {
         passkeys?: string;
     };
     /**
-     * API key scopes configuration.
-     * Controls which permission scopes are available when creating API keys.
-     * When not provided, scopes are auto-generated from Payload collections.
+     * API key permissions configuration.
+     * Controls which permissions are available when creating API keys.
+     * When not provided, permissions are auto-generated from Payload collections.
      */
-    apiKey?: ApiKeyScopesConfig;
+    apiKey?: ApiKeyPermissionsConfig;
 };
 export type BetterAuthPluginOptions = {
     /**
@@ -133,10 +133,10 @@ export type BetterAuthPluginOptions = {
     admin?: BetterAuthPluginAdminOptions;
 };
 /**
- * Get the configured API key scopes config.
- * Used by the ApiKeysView to build available scopes.
+ * Get the stored API key permissions config.
+ * Used by the ApiKeysView server component to generate permission definitions.
  */
-export declare function getApiKeyScopesConfig(): ApiKeyScopesConfig | undefined;
+export declare function getApiKeyPermissionsConfig(): ApiKeyPermissionsConfig | undefined;
 /**
  * Payload plugin that initializes Better Auth.
  *

package/dist/plugin/index.js

@@ -4,22 +4,21 @@
  * @packageDocumentation
  */ 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
-let apiKeyScopesConfig = undefined;
+// Store API key permissions config for access by management views
+let apiKeyPermissionsConfig = undefined;
 /**
- * Get the configured API key scopes config.
- * Used by the ApiKeysView to build available scopes.
- */ export function getApiKeyScopesConfig() {
-    return apiKeyScopesConfig;
+ * Get the stored API key permissions config.
+ * Used by the ApiKeysView server component to generate permission definitions.
+ */ export function getApiKeyPermissionsConfig() {
+    return apiKeyPermissionsConfig;
 }
 /**
- * Handle API key creation with scopes server-side.
- * Converts scopes to permissions and calls Better Auth's server API.
- */ async function handleApiKeyCreateWithScopes(authApi, payload, headers, body) {
+ * Handle API key creation server-side.
+ * Passes permissions directly from the client to Better Auth's server API.
+ */ async function handleApiKeyCreate(authApi, headers, body) {
     try {
         // Get the current session to find the user
         const session = await authApi.getSession({
@@ -35,16 +34,8 @@ let apiKeyScopesConfig = undefined;
                 }
             });
         }
-        // Extract scopes from the request body
-        const scopes = body.scopes ?? [];
-        // Build permissions from scopes if any are provided
-        let permissions;
-        if (scopes.length > 0) {
-            const scopesConfig = getApiKeyScopesConfig();
-            const availableScopes = buildAvailableScopes(payload.config.collections, scopesConfig);
-            permissions = scopesToPermissions(scopes, availableScopes);
-        }
-        // Build the API key creation options
+        // Permissions come directly from the client in BA's native format
+        const permissions = body.permissions;
         const createOptions = {
             body: {
                 name: body.name,
@@ -52,10 +43,7 @@ let apiKeyScopesConfig = undefined;
                 expiresIn: body.expiresIn,
                 prefix: body.prefix,
                 permissions: permissions && Object.keys(permissions).length > 0 ? permissions : undefined,
-                metadata: scopes.length > 0 ? {
-                    ...body.metadata,
-                    scopes
-                } : body.metadata
+                metadata: body.metadata
             }
         };
         // Call Better Auth's server-side API
@@ -69,38 +57,13 @@ let apiKeyScopesConfig = undefined;
                 }
             });
         }
-        try {
-            const result = await authApi.createApiKey(createOptions);
-            return new Response(JSON.stringify(result), {
-                status: 200,
-                headers: {
-                    'Content-Type': 'application/json'
-                }
-            });
-        } catch (createError) {
-            // Check if error is due to metadata being disabled
-            const errorMessage = createError instanceof Error ? createError.message : String(createError);
-            const isMetadataDisabled = errorMessage.toLowerCase().includes('metadata') && errorMessage.toLowerCase().includes('disabled');
-            if (isMetadataDisabled && createOptions.body.metadata) {
-                // Retry without metadata - key will still work, just won't show scopes in UI
-                console.warn('[better-auth] Metadata disabled, creating API key without scope metadata. Enable metadata with apiKey({ enableMetadata: true }) for better UX.');
-                const optionsWithoutMetadata = {
-                    body: {
-                        ...createOptions.body,
-                        metadata: undefined
-                    }
-                };
-                const result = await authApi.createApiKey(optionsWithoutMetadata);
-                return new Response(JSON.stringify(result), {
-                    status: 200,
-                    headers: {
-                        'Content-Type': 'application/json'
-                    }
-                });
+        const result = await authApi.createApiKey(createOptions);
+        return new Response(JSON.stringify(result), {
+            status: 200,
+            headers: {
+                'Content-Type': 'application/json'
             }
-            // Re-throw other errors
-            throw createError;
-        }
+        });
     } catch (error) {
         console.error('[better-auth] API key creation error:', error);
         const message = error instanceof Error ? error.message : 'Failed to create API key';
@@ -171,9 +134,10 @@ let apiKeyScopesConfig = undefined;
                     }
                 }
             }
-            // Guard API key mutation endpoints — require admin role
+            // Guard API key mutation and list 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 isApiKeyList = req.method === 'GET' && pathname.endsWith('/api-key/list');
+            if (isApiKeyMutation || isApiKeyList) {
                 const session = await auth.api.getSession({
                     headers: req.headers
                 });
@@ -188,7 +152,7 @@ let apiKeyScopesConfig = undefined;
                     });
                 }
                 // Resolve required role: apiKey config > login config > default 'admin'
-                const requiredRole = apiKeyScopesConfig?.requiredRole ?? adminOptions?.login?.requiredRole ?? 'admin';
+                const requiredRole = apiKeyPermissionsConfig?.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';
@@ -210,11 +174,10 @@ let apiKeyScopesConfig = undefined;
                     }
                 }
             }
-            // 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);
+            // Intercept API key creation requests to inject userId from session
+            const isApiKeyCreate = req.method === 'POST' && pathname.endsWith('/api-key/create');
             if (isApiKeyCreate && parsedBody) {
-                return handleApiKeyCreateWithScopes(auth.api, req.payload, req.headers, parsedBody);
+                return handleApiKeyCreate(auth.api, req.headers, parsedBody);
             }
             // Create a new Request for Better Auth
             const request = new Request(url.toString(), {
@@ -436,8 +399,8 @@ let apiKeyScopesConfig = undefined;
  * ```
  */ export function createBetterAuthPlugin(options) {
     const { createAuth, authBasePath = '/auth', autoRegisterEndpoints = true, autoInjectAdminComponents = true } = options;
-    // Store API key scopes config for access by management views
-    apiKeyScopesConfig = options.admin?.apiKey;
+    // Store API key permissions config for access by management views
+    apiKeyPermissionsConfig = options.admin?.apiKey;
     return (incomingConfig)=>{
         // Inject admin components if enabled
         let config = autoInjectAdminComponents ? injectAdminComponents(incomingConfig, options) : incomingConfig;

package/dist/types/apiKey.d.ts

@@ -1,55 +1,34 @@
 /**
- * API Key Scope Types
+ * API Key Permission Types
  *
- * Provides typed configuration for API key permission scopes.
+ * Uses Better Auth's native permission format: Record<string, string[]>
+ * where keys are resource names (collection slugs) and values are action arrays.
+ *
+ * Convention: two actions per collection — 'read' and 'write'.
+ * - read: view records
+ * - write: full access (create, update, delete) — implies read
  */
 /**
- * A single permission scope definition.
- * Scopes are human-readable permission groups (like GitHub OAuth scopes).
+ * A permission definition for the admin UI.
+ * Describes a collection's available permission levels.
  */
-export type ScopeDefinition = {
-    /** Human-readable label for the scope (e.g., "Read Content") */
+export type PermissionDefinition = {
+    /** Collection slug (e.g., 'posts') */
+    slug: string;
+    /** Human-readable label (e.g., 'Posts') */
     label: string;
-    /** Description of what this scope allows (e.g., "View posts, pages, and comments") */
-    description: string;
-    /**
-     * Permission mapping: { resourceType: ['action1', 'action2'] }
-     * Maps to Better Auth's permission format.
-     * Use '*' for resource to match all resources.
-     * Use '*' in actions array to grant all actions on a resource.
-     */
-    permissions: Record<string, string[]>;
-    /** If true, only admin users can create keys with this scope */
-    adminOnly?: boolean;
+    /** Available actions — always ['read', 'write'] for auto-generated */
+    actions: string[];
 };
 /**
- * Configuration options for API key scopes.
- * Can be used in plugin options to customize available scopes.
+ * Configuration options for API key permissions.
  */
-export type ApiKeyScopesConfig = {
-    /**
-     * Custom scope definitions.
-     * Key is the scope ID (e.g., 'content:read'), value is the scope definition.
-     */
-    scopes?: Record<string, ScopeDefinition>;
-    /**
-     * Include auto-generated collection scopes.
-     * When true (default), generates {collection}:read, {collection}:write, {collection}:delete
-     * for each Payload collection.
-     * @default true when no custom scopes provided, false when custom scopes provided
-     */
-    includeCollectionScopes?: boolean;
+export type ApiKeyPermissionsConfig = {
     /**
-     * Collections to exclude from auto-generated scopes.
-     * Useful for hiding sensitive collections like 'sessions' or 'verifications'.
-     * @default ['sessions', 'verifications', 'accounts', 'twoFactors']
+     * Collections to exclude from the permissions UI.
+     * @default ['sessions', 'verifications', 'accounts', 'twoFactors', 'apiKeys']
      */
     excludeCollections?: string[];
-    /**
-     * Default scopes assigned to new API keys when user doesn't select any.
-     * 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')
@@ -59,10 +38,3 @@ export type ApiKeyScopesConfig = {
      */
     requiredRole?: string | string[] | null;
 };
-/**
- * Scope data passed to the API keys management client component.
- */
-export type AvailableScope = ScopeDefinition & {
-    /** The scope ID (e.g., 'content:read') */
-    id: string;
-};

package/dist/types/apiKey.js

@@ -1,10 +1,15 @@
 /**
- * API Key Scope Types
+ * API Key Permission Types
  *
- * Provides typed configuration for API key permission scopes.
+ * Uses Better Auth's native permission format: Record<string, string[]>
+ * where keys are resource names (collection slugs) and values are action arrays.
+ *
+ * Convention: two actions per collection — 'read' and 'write'.
+ * - read: view records
+ * - write: full access (create, update, delete) — implies read
  */ /**
- * A single permission scope definition.
- * Scopes are human-readable permission groups (like GitHub OAuth scopes).
+ * A permission definition for the admin UI.
+ * Describes a collection's available permission levels.
  */ /**
- * Scope data passed to the API keys management client component.
+ * Configuration options for API key permissions.
  */ export { };

package/dist/utils/apiKeyAccess.d.ts

@@ -1,46 +1,26 @@
 /**
- * API Key Scope Enforcement Utilities
+ * API Key Permission Enforcement Utilities
  *
- * These utilities help enforce API key scopes in Payload access control.
- * They extract the API key from requests, validate scopes, and provide
- * type-safe access control functions.
+ * Thin wrappers around Better Auth's verifyApiKey() for use in
+ * Payload access control. Uses BA's native permission format.
  *
  * @example
  * ```ts
- * import { requireScope, requireAnyScope } from '@delmaredigital/payload-better-auth'
+ * import { requirePermission, allowSessionOrPermission } from '@delmaredigital/payload-better-auth'
  *
  * export const Posts: CollectionConfig = {
  *   slug: 'posts',
  *   access: {
- *     read: requireAnyScope(['posts:read', 'content:read']),
- *     create: requireScope('posts:write'),
- *     update: requireScope('posts:write'),
- *     delete: requireScope('posts:delete'),
+ *     read: requirePermission('posts', 'read'),
+ *     create: requirePermission('posts', 'write'),
+ *     update: requirePermission('posts', 'write'),
+ *     delete: requirePermission('posts', 'write'),
  *   },
  * }
  * ```
  */
 import type { Access, PayloadRequest } from 'payload';
-export type ApiKeyInfo = {
-    /** The API key ID */
-    id: string;
-    /** Reference ID (user or organization) who owns this key */
-    referenceId: string;
-    /** Reference type - whether key is owned by a user or organization */
-    referenceType: 'user' | 'organization';
-    /** Array of granted scope strings */
-    scopes: string[];
-    /** The raw key (only first/last chars visible) */
-    keyPrefix?: string;
-    /** Optional metadata */
-    metadata?: Record<string, unknown>;
-};
-export type ApiKeyAccessConfig = {
-    /**
-     * API keys collection slug.
-     * @default 'apiKeys' or 'api-keys' (auto-detected)
-     */
-    apiKeysCollection?: string;
+export type ApiKeyPermissionConfig = {
     /**
      * Allow access if user is authenticated (non-API key session).
      * Useful for allowing both API keys and regular sessions.
@@ -53,121 +33,93 @@ export type ApiKeyAccessConfig = {
      */
     extractApiKey?: (req: PayloadRequest) => string | null;
 };
+/** A single permission check: resource + action */
+export type PermissionCheck = {
+    resource: string;
+    action: string;
+};
 /**
  * Extract API key from request headers.
  * Supports Bearer token format: Authorization: Bearer <api-key>
  */
 export declare function extractApiKeyFromRequest(req: PayloadRequest): string | null;
 /**
- * Look up API key info from the database.
- * Returns null if key not found or disabled.
- */
-export declare function getApiKeyInfo(req: PayloadRequest, apiKey: string, apiKeysCollection?: string): Promise<ApiKeyInfo | null>;
-/**
- * Check if an API key has a specific scope.
- * Supports wildcard patterns like 'posts:*' matching 'posts:read', 'posts:write', etc.
- */
-export declare function hasScope(keyScopes: string[], requiredScope: string): boolean;
-/**
- * Check if an API key has any of the specified scopes.
- */
-export declare function hasAnyScope(keyScopes: string[], requiredScopes: string[]): boolean;
-/**
- * Check if an API key has all of the specified scopes.
- */
-export declare function hasAllScopes(keyScopes: string[], requiredScopes: string[]): boolean;
-/**
- * Create an access control function that requires a specific scope.
+ * Require a specific permission on an API key.
  *
- * @param scope - The required scope string (e.g., 'posts:read')
- * @param config - Configuration options
+ * @param resource - Collection slug (e.g., 'posts')
+ * @param action - Permission action: 'read' or 'write'
+ * @param config - Optional configuration
  * @returns Payload access function
  *
  * @example
  * ```ts
  * access: {
- *   read: requireScope('posts:read'),
- *   create: requireScope('posts:write'),
+ *   read: requirePermission('posts', 'read'),
+ *   create: requirePermission('posts', 'write'),
  * }
  * ```
  */
-export declare function requireScope(scope: string, config?: ApiKeyAccessConfig): Access;
+export declare function requirePermission(resource: string, action: string, config?: ApiKeyPermissionConfig): Access;
 /**
- * Create an access control function that requires any of the specified scopes.
+ * Require any one of the specified permissions.
  *
- * @param scopes - Array of acceptable scopes (at least one must match)
- * @param config - Configuration options
+ * @param permissions - Array of {resource, action} pairs (at least one must match)
+ * @param config - Optional configuration
  * @returns Payload access function
  *
  * @example
  * ```ts
  * access: {
- *   read: requireAnyScope(['posts:read', 'content:read', 'admin:*']),
+ *   read: requireAnyPermission([
+ *     { resource: 'posts', action: 'read' },
+ *     { resource: 'pages', action: 'read' },
+ *   ]),
  * }
  * ```
  */
-export declare function requireAnyScope(scopes: string[], config?: ApiKeyAccessConfig): Access;
+export declare function requireAnyPermission(permissions: PermissionCheck[], config?: ApiKeyPermissionConfig): Access;
 /**
- * Create an access control function that requires all specified scopes.
+ * Require all of the specified permissions.
  *
- * @param scopes - Array of required scopes (all must be present)
- * @param config - Configuration options
+ * @param permissions - Array of {resource, action} pairs (all must match)
+ * @param config - Optional configuration
  * @returns Payload access function
  *
  * @example
  * ```ts
  * access: {
- *   delete: requireAllScopes(['posts:delete', 'admin:write']),
+ *   delete: requireAllPermissions([
+ *     { resource: 'posts', action: 'write' },
+ *     { resource: 'admin', action: 'write' },
+ *   ]),
  * }
  * ```
  */
-export declare function requireAllScopes(scopes: string[], config?: ApiKeyAccessConfig): Access;
+export declare function requireAllPermissions(permissions: PermissionCheck[], config?: ApiKeyPermissionConfig): Access;
 /**
- * Create an access control function that allows either:
- * 1. Authenticated users (via session)
- * 2. API key with required scope
- *
- * This is useful for endpoints that should work with both auth methods.
- *
- * @param scope - The required scope for API key access
- * @param config - Configuration options
- * @returns Payload access function
+ * Allow either authenticated session OR API key with permission.
  *
  * @example
  * ```ts
  * access: {
- *   read: allowSessionOrScope('posts:read'),
+ *   read: allowSessionOrPermission('posts', 'read'),
  * }
  * ```
  */
-export declare function allowSessionOrScope(scope: string, config?: Omit<ApiKeyAccessConfig, 'allowAuthenticatedUsers'>): Access;
+export declare function allowSessionOrPermission(resource: string, action: string, config?: Omit<ApiKeyPermissionConfig, 'allowAuthenticatedUsers'>): Access;
 /**
- * Create an access control function that allows either:
- * 1. Authenticated users (via session)
- * 2. API key with any of the required scopes
- *
- * @param scopes - Array of acceptable scopes for API key access
- * @param config - Configuration options
- * @returns Payload access function
+ * Allow either authenticated session OR API key with any of the permissions.
  */
-export declare function allowSessionOrAnyScope(scopes: string[], config?: Omit<ApiKeyAccessConfig, 'allowAuthenticatedUsers'>): Access;
+export declare function allowSessionOrAnyPermission(permissions: PermissionCheck[], config?: Omit<ApiKeyPermissionConfig, 'allowAuthenticatedUsers'>): Access;
 /**
- * Validate an API key and get its info.
- *
- * This performs a database lookup to validate the key and retrieve
- * its associated scopes and user.
- *
- * @param req - Payload request
- * @param apiKeysCollection - The API keys collection slug
- * @returns API key info if valid, null otherwise
+ * Require a valid API key (no specific permissions checked).
+ * Useful for apps that use role-based access and just need to verify the key exists.
  *
  * @example
  * ```ts
- * const keyInfo = await validateApiKey(req)
- * if (keyInfo) {
- *   console.log('Valid API key for:', keyInfo.referenceId, keyInfo.referenceType)
- *   console.log('Scopes:', keyInfo.scopes)
+ * access: {
+ *   read: requireApiKey(),
  * }
  * ```
  */
-export declare function validateApiKey(req: PayloadRequest, apiKeysCollection?: string): Promise<ApiKeyInfo | null>;
+export declare function requireApiKey(config?: ApiKeyPermissionConfig): Access;