better_auth-api-key 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dd667853c3c3130a0d0bcd0ebd00a5f15425de87979f2cdc00b2a2f5d9001fe
-  data.tar.gz: f7222b9e0c3a61aabe67ec70ddefbc428f2d39e2181b53586e275ef3b9a63867
+  metadata.gz: '0644878a04c3b9f3489304b324a9636aed5411eefc8b8f51ec89f15a5b978cf1'
+  data.tar.gz: fc6aa4568b7831ec89a1fbab0abd5191b0d27bf5f5afc84615c038748dce9bd0
 SHA512:
-  metadata.gz: a36b2eaee2a0128a50276eff4ccfbfa7604ea06364a041e7f039d6d10f7a3b17216ccb36fff7470e2918148a437ac0fce3801677ed3ca71dc843883c7d3e364d
-  data.tar.gz: 3ecc422678b620d01b9c6848d60609246c3194e479d629d60ec21d92f8f7be330eade4a96e6971104da7bb62422e334e31d8069816a847df46ded0da005bc89e
+  metadata.gz: 2790364cbe835dd0c368aa9a035a57653370ab5d7f06c13fe1967ef04442a1cf3554a61056c920d80d0834ba9fd1c4963206ba46cb9b5f2bea77d46bcef59f42
+  data.tar.gz: 170f42d1487f231cb0302a63cd26e90d72f0560f0c0cc9ad5cbb05a7863d842c70517699432afa800c9070a6d1cbbf44e924dfca361972568a0dddae8759cfd8

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-05-21
+
+- Improved adapter coverage and Redis-backed storage behavior for API key flows.
+- Tightened API key listing behavior so responses stay consistent across supported adapters.
+
 ## 0.7.0 - 2026-05-05
 
 - Changed API-key-backed sessions to expose `tokenFingerprint` instead of storing the raw API key in `session["token"]`.

data/lib/better_auth/api_key/adapter.rb

@@ -84,8 +84,10 @@ module BetterAuth
           updated = nil
           if config[:storage] == "database" || config[:fallback_to_database]
             updated = ctx.context.adapter.update(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}], update: update)
+            return nil unless updated
+          else
+            updated = record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
           end
-          updated ||= record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
           set(ctx, updated, config) if config[:storage] == "secondary-storage"
           updated
         end

data/lib/better_auth/api_key/routes/create_api_key.rb

@@ -9,10 +9,13 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/create", method: "POST") do |ctx|
+          BetterAuth::Endpoint.new(path: "/api-key/create", method: "POST", metadata: Routes.openapi_for(:create_api_key)) do |ctx|
             body = BetterAuth::Plugins.api_key_normalize_body(ctx.body)
             resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, body[:config_id])
             session = BetterAuth::Routes.current_session(ctx, allow_nil: true)
+            if !session && BetterAuth::Plugins.api_key_auth_required?(ctx)
+              raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"])
+            end
             reference_id = BetterAuth::Plugins.api_key_create_reference_id!(ctx, body, session, resolved_config)
 
             BetterAuth::Plugins.api_key_validate_create_update!(body, resolved_config, create: true, client: !ctx.headers.empty?)

data/lib/better_auth/api_key/routes/delete_all_expired_api_keys.rb

@@ -9,8 +9,8 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/delete-all-expired-api-keys", method: "POST") do |ctx|
-            BetterAuth::Plugins.api_key_delete_expired(ctx.context, config, bypass_last_check: true)
+          BetterAuth::Endpoint.new(path: "/api-key/delete-all-expired-api-keys", method: "POST", metadata: Routes.openapi_for(:delete_all_expired_api_keys)) do |ctx|
+            BetterAuth::APIKey::Routes.delete_expired(ctx.context, config, bypass_last_check: true, raise_on_error: true)
             ctx.json({success: true, error: nil})
           rescue => error
             ctx.context.logger.error("[API KEY PLUGIN] Failed to delete expired API keys: #{error.message}") if ctx.context.logger.respond_to?(:error)

data/lib/better_auth/api_key/routes/delete_api_key.rb

@@ -9,7 +9,7 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/delete", method: "POST") do |ctx|
+          BetterAuth::Endpoint.new(path: "/api-key/delete", method: "POST", metadata: Routes.openapi_for(:delete_api_key)) do |ctx|
             session = BetterAuth::Routes.current_session(ctx)
             raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USER_BANNED"]) if session[:user]["banned"] == true
 

data/lib/better_auth/api_key/routes/get_api_key.rb

@@ -9,7 +9,7 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/get", method: "GET") do |ctx|
+          BetterAuth::Endpoint.new(path: "/api-key/get", method: "GET", metadata: Routes.openapi_for(:get_api_key)) do |ctx|
             session = BetterAuth::Routes.current_session(ctx)
             query = BetterAuth::Plugins.normalize_hash(ctx.query)
             resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, query[:config_id])

data/lib/better_auth/api_key/routes/index.rb

@@ -42,7 +42,7 @@ module BetterAuth
 
       @last_expired_check = nil
 
-      def delete_expired(context, config, bypass_last_check: false)
+      def delete_expired(context, config, bypass_last_check: false, raise_on_error: false)
         return unless config[:storage] == "database" || config[:fallback_to_database]
         unless bypass_last_check
           now = Time.now
@@ -59,6 +59,9 @@ module BetterAuth
             {field: "expiresAt", value: nil, operator: "ne"}
           ]
         )
+      rescue => error
+        context.logger.error("[API KEY PLUGIN] Failed to delete expired API keys: #{error.message}") if context.respond_to?(:logger) && context.logger.respond_to?(:error)
+        raise if raise_on_error
       end
 
       def schedule_cleanup(ctx, config)
@@ -69,6 +72,227 @@ module BetterAuth
           task.call
         end
       end
+
+      def openapi_for(route)
+        {
+          create_api_key: create_api_key_openapi,
+          verify_api_key: verify_api_key_openapi,
+          get_api_key: get_api_key_openapi,
+          update_api_key: update_api_key_openapi,
+          delete_api_key: delete_api_key_openapi,
+          list_api_keys: list_api_keys_openapi,
+          delete_all_expired_api_keys: delete_all_expired_api_keys_openapi
+        }.fetch(route)
+      end
+
+      def create_api_key_openapi
+        {
+          openapi: {
+            description: "Create a new API key for a user",
+            requestBody: BetterAuth::OpenAPI.json_request_body(api_key_create_body_schema, required: true),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key created successfully", api_key_record_schema(include_secret: true))
+            }
+          }
+        }
+      end
+
+      def verify_api_key_openapi
+        {
+          openapi: {
+            description: "Verify and rate-limit an API key",
+            requestBody: BetterAuth::OpenAPI.json_request_body(
+              BetterAuth::OpenAPI.object_schema(
+                {
+                  key: {type: "string", description: "The API key to verify"},
+                  configId: {type: "string", description: "Configuration ID to use for the lookup"},
+                  permissions: api_key_permissions_schema.merge(description: "Permissions required for the request")
+                },
+                required: ["key"]
+              )
+            ),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response(
+                "API key verification result",
+                BetterAuth::OpenAPI.object_schema(
+                  {
+                    valid: {type: "boolean"},
+                    error: {type: ["object", "null"], additionalProperties: true},
+                    key: api_key_record_schema(include_secret: false).merge(type: ["object", "null"])
+                  },
+                  required: ["valid", "error", "key"]
+                )
+              )
+            }
+          }
+        }
+      end
+
+      def get_api_key_openapi
+        {
+          openapi: {
+            description: "Get an API key by ID",
+            parameters: [
+              BetterAuth::OpenAPI.query_parameter("id", required: true, description: "The API key ID"),
+              BetterAuth::OpenAPI.query_parameter("configId", description: "Configuration ID to use for the lookup")
+            ],
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key retrieved successfully", api_key_record_schema(include_secret: false))
+            }
+          }
+        }
+      end
+
+      def update_api_key_openapi
+        {
+          openapi: {
+            description: "Update an existing API key by ID",
+            requestBody: BetterAuth::OpenAPI.json_request_body(api_key_update_body_schema, required: true),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key updated successfully", api_key_record_schema(include_secret: false))
+            }
+          }
+        }
+      end
+
+      def delete_api_key_openapi
+        {
+          openapi: {
+            description: "Delete an API key by ID",
+            requestBody: BetterAuth::OpenAPI.json_request_body(
+              BetterAuth::OpenAPI.object_schema(
+                {
+                  keyId: {type: "string", description: "The API key ID"},
+                  configId: {type: "string", description: "Configuration ID to use for the lookup"}
+                },
+                required: ["keyId"]
+              )
+            ),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key deleted successfully", BetterAuth::OpenAPI.success_response_schema)
+            }
+          }
+        }
+      end
+
+      def list_api_keys_openapi
+        {
+          openapi: {
+            description: "List all API keys for the authenticated user or for a specific organization",
+            parameters: [
+              BetterAuth::OpenAPI.query_parameter("configId", description: "Filter by configuration ID"),
+              BetterAuth::OpenAPI.query_parameter("organizationId", description: "Organization ID to list keys for"),
+              BetterAuth::OpenAPI.query_parameter("limit", schema: {type: "number"}, description: "The number of API keys to return"),
+              BetterAuth::OpenAPI.query_parameter("offset", schema: {type: "number"}, description: "The offset to start from"),
+              BetterAuth::OpenAPI.query_parameter("sortBy", description: "The field to sort by"),
+              BetterAuth::OpenAPI.query_parameter("sortDirection", schema: {type: "string", enum: ["asc", "desc"]}, description: "The direction to sort by")
+            ],
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response(
+                "API keys retrieved successfully",
+                BetterAuth::OpenAPI.object_schema(
+                  {
+                    apiKeys: BetterAuth::OpenAPI.array_schema(api_key_record_schema(include_secret: false)),
+                    total: {type: "number"},
+                    limit: {type: ["number", "null"]},
+                    offset: {type: ["number", "null"]}
+                  },
+                  required: ["apiKeys", "total"]
+                )
+              )
+            }
+          }
+        }
+      end
+
+      def delete_all_expired_api_keys_openapi
+        {
+          openapi: {
+            description: "Delete all expired API keys",
+            requestBody: BetterAuth::OpenAPI.empty_request_body,
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response(
+                "Expired API key cleanup result",
+                BetterAuth::OpenAPI.object_schema(
+                  {
+                    success: {type: "boolean"},
+                    error: {type: ["object", "null"], additionalProperties: true}
+                  },
+                  required: ["success", "error"]
+                )
+              )
+            }
+          }
+        }
+      end
+
+      def api_key_create_body_schema
+        BetterAuth::OpenAPI.object_schema(
+          {
+            configId: {type: "string", description: "The configuration ID to use for the API key"},
+            name: {type: "string", description: "Name of the API key"},
+            expiresIn: {type: ["number", "null"], description: "Expiration time of the API key in seconds"},
+            prefix: {type: "string", description: "Prefix of the API key"},
+            remaining: {type: ["number", "null"], description: "Remaining number of requests"},
+            metadata: {nullable: true, description: "Metadata associated with the API key"},
+            refillAmount: {type: "number", description: "Amount to refill the remaining count"},
+            refillInterval: {type: "number", description: "Interval to refill the API key in milliseconds"},
+            rateLimitTimeWindow: {type: "number", description: "Rate limit time window in milliseconds"},
+            rateLimitMax: {type: "number", description: "Maximum requests allowed within a window"},
+            rateLimitEnabled: {type: "boolean", description: "Whether the key has rate limiting enabled"},
+            permissions: api_key_permissions_schema.merge(description: "Permissions of the API key"),
+            userId: {type: "string", description: "User ID that the API key belongs to"},
+            organizationId: {type: "string", description: "Organization ID that the API key belongs to"}
+          }
+        )
+      end
+
+      def api_key_update_body_schema
+        BetterAuth::OpenAPI.object_schema(
+          api_key_create_body_schema[:properties].merge(
+            keyId: {type: "string", description: "The API key ID"},
+            enabled: {type: "boolean", description: "Whether the API key is enabled"}
+          ).except(:prefix, :organizationId),
+          required: ["keyId"]
+        )
+      end
+
+      def api_key_permissions_schema
+        {
+          type: "object",
+          additionalProperties: {
+            type: "array",
+            items: {type: "string"}
+          }
+        }
+      end
+
+      def api_key_record_schema(include_secret:)
+        properties = {
+          id: {type: "string", description: "Unique identifier of the API key"},
+          createdAt: {type: "string", format: "date-time", description: "Creation timestamp"},
+          updatedAt: {type: "string", format: "date-time", description: "Last update timestamp"},
+          name: {type: ["string", "null"], description: "Name of the API key"},
+          start: {type: ["string", "null"], description: "Starting characters of the key"},
+          prefix: {type: ["string", "null"], description: "Prefix of the API key"},
+          enabled: {type: "boolean", description: "Whether the key is enabled"},
+          expiresAt: {type: ["string", "null"], format: "date-time", description: "Expiration timestamp"},
+          referenceId: {type: "string", description: "ID of the reference owning the key"},
+          lastRefillAt: {type: ["string", "null"], format: "date-time", description: "Last refill timestamp"},
+          lastRequest: {type: ["string", "null"], format: "date-time", description: "Last request timestamp"},
+          metadata: {type: ["object", "null"], additionalProperties: true, description: "Metadata associated with the key"},
+          rateLimitMax: {type: ["number", "null"], description: "Maximum requests in time window"},
+          rateLimitTimeWindow: {type: ["number", "null"], description: "Rate limit time window in milliseconds"},
+          rateLimitEnabled: {type: "boolean", description: "Whether rate limiting is enabled"},
+          remaining: {type: ["number", "null"], description: "Remaining number of requests"},
+          refillAmount: {type: ["number", "null"], description: "Amount to refill"},
+          refillInterval: {type: ["number", "null"], description: "Refill interval in milliseconds"},
+          permissions: api_key_permissions_schema.merge(nullable: true, description: "Permissions of the API key"),
+          userId: {type: ["string", "null"], description: "ID of the user owning the key"}
+        }
+        properties[:key] = {type: "string", description: "The full API key"} if include_secret
+        BetterAuth::OpenAPI.object_schema(properties)
+      end
     end
   end
 end

data/lib/better_auth/api_key/routes/list_api_keys.rb

@@ -9,28 +9,35 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/list", method: "GET") do |ctx|
+          BetterAuth::Endpoint.new(path: "/api-key/list", method: "GET", metadata: Routes.openapi_for(:list_api_keys)) do |ctx|
             session = BetterAuth::Routes.current_session(ctx)
             query = BetterAuth::Plugins.normalize_hash(ctx.query)
             BetterAuth::Plugins.api_key_validate_list_query!(query)
-            configs = query[:config_id] ? [BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, query[:config_id])] : config.fetch(:configurations, [config])
+            configs = query[:config_id] ? [BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, query[:config_id])] : storage_groups(config.fetch(:configurations, [config]))
             reference_id = query[:organization_id] || session[:user]["id"]
             expected_reference = query[:organization_id] ? "organization" : "user"
             BetterAuth::Plugins.api_key_check_org_permission!(ctx, session[:user]["id"], reference_id, "read") if query[:organization_id]
-            records = configs.flat_map { |entry| BetterAuth::Plugins.api_key_list_for_reference(ctx, reference_id, entry) }.uniq { |record| record["id"] }
-            records = records.select do |record|
-              record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
-              record_config[:references].to_s == expected_reference &&
-                BetterAuth::Plugins.api_key_record_reference_id(record) == reference_id &&
-                (!query[:config_id] || BetterAuth::Plugins.api_key_config_id_matches?(BetterAuth::Plugins.api_key_record_config_id(record), query[:config_id]))
-            end
-            total = records.length
-            records = BetterAuth::Plugins.api_key_sort_records(records, query[:sort_by], query[:sort_direction])
             offset = query.key?(:offset) ? query[:offset].to_i : nil
             limit = query.key?(:limit) ? query[:limit].to_i : nil
-            records = records.drop(offset) if offset
-            records = records.first(limit) if limit
-            records.each { |record| BetterAuth::Plugins.api_key_delete_expired(ctx.context, BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))) }
+            pushed = database_paginated_records(ctx, configs.first, reference_id, expected_reference, query, limit, offset)
+            if pushed
+              records = pushed.fetch(:records)
+              total = pushed.fetch(:total)
+            else
+              records = configs.flat_map { |entry| BetterAuth::Plugins.api_key_list_for_reference(ctx, reference_id, entry) }.uniq { |record| record["id"] }
+              records = records.select do |record|
+                record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+                record_config[:references].to_s == expected_reference &&
+                  BetterAuth::Plugins.api_key_record_reference_id(record) == reference_id &&
+                  (!query[:config_id] || BetterAuth::Plugins.api_key_config_id_matches?(BetterAuth::Plugins.api_key_record_config_id(record), query[:config_id]))
+              end
+              total = records.length
+              records = BetterAuth::Plugins.api_key_sort_records(records, query[:sort_by], query[:sort_direction])
+              records = records.drop(offset) if offset
+              records = records.first(limit) if limit
+            end
+            cleanup_config = query[:config_id] ? configs.first : config
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, cleanup_config)
             migration_records = records.select { |record| BetterAuth::APIKey::Adapter.legacy_metadata_migration_needed?(record) }
             if migration_records.any?
               BetterAuth::APIKey::Utils.run_background_task(
@@ -50,6 +57,62 @@ module BetterAuth
             ctx.json({apiKeys: api_keys, total: total, limit: limit, offset: offset})
           end
         end
+
+        def storage_groups(configurations)
+          seen = {}
+          configurations.each_with_object([]) do |entry, groups|
+            key = storage_identifier(entry)
+            next if seen[key]
+
+            seen[key] = true
+            groups << entry
+          end
+        end
+
+        def storage_identifier(config)
+          return "database" if config[:storage].to_s == "database"
+          return "custom:#{config[:config_id] || "default"}" if config[:custom_storage]
+
+          config[:fallback_to_database] ? "secondary-storage-with-fallback" : "secondary-storage"
+        end
+
+        def database_paginated_records(ctx, config, reference_id, expected_reference, query, limit, offset)
+          return nil unless query[:config_id] && config
+          return nil unless config[:storage].to_s == "database"
+          return nil if BetterAuth::APIKey::Routes.default_config_id?(query[:config_id])
+          return nil unless config[:references].to_s == expected_reference
+          return nil if expected_reference == "user" && legacy_user_id_records?(ctx, reference_id, query[:config_id])
+
+          where = [
+            {field: "referenceId", value: reference_id},
+            {field: "configId", value: query[:config_id]}
+          ]
+          sort_by = query[:sort_by] ? {field: query[:sort_by].to_s, direction: (query[:sort_direction] || "asc").to_s} : nil
+          {
+            records: ctx.context.adapter.find_many(
+              model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+              where: where,
+              sort_by: sort_by,
+              limit: limit,
+              offset: offset
+            ),
+            total: ctx.context.adapter.count(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: where)
+          }
+        end
+
+        def legacy_user_id_records?(ctx, reference_id, config_id)
+          where = [
+            {field: "userId", value: reference_id},
+            {field: "configId", value: config_id}
+          ]
+          ctx.context.adapter.count(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: where).positive?
+        rescue KeyError, NoMethodError
+          false
+        rescue BetterAuth::Error => error
+          raise unless error.message.include?("Field userId not found")
+
+          false
+        end
       end
     end
   end

data/lib/better_auth/api_key/routes/update_api_key.rb

@@ -9,10 +9,13 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/update", method: "POST") do |ctx|
+          BetterAuth::Endpoint.new(path: "/api-key/update", method: "POST", metadata: Routes.openapi_for(:update_api_key)) do |ctx|
             body = BetterAuth::Plugins.api_key_normalize_body(ctx.body)
             resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, body[:config_id])
             session = BetterAuth::Routes.current_session(ctx, allow_nil: true)
+            if !session && BetterAuth::Plugins.api_key_auth_required?(ctx)
+              raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"])
+            end
             user_id = session&.dig(:user, "id") || body[:user_id]
             raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"]) unless user_id
             if session && body[:user_id] && body[:user_id] != session[:user]["id"]
@@ -34,6 +37,13 @@ module BetterAuth
             raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["NO_VALUES_TO_UPDATE"]) if update.empty?
 
             updated = BetterAuth::Plugins.api_key_update_record(ctx, record, update.merge(updatedAt: Time.now), record_config)
+            unless updated
+              raise BetterAuth::APIError.new(
+                "INTERNAL_SERVER_ERROR",
+                message: BetterAuth::Plugins::API_KEY_ERROR_CODES["FAILED_TO_UPDATE_API_KEY"],
+                code: "FAILED_TO_UPDATE_API_KEY"
+              )
+            end
             updated = BetterAuth::Plugins.api_key_migrate_legacy_metadata(ctx, updated, record_config)
             BetterAuth::Plugins.api_key_delete_expired(ctx.context, record_config)
             ctx.json(BetterAuth::Plugins.api_key_public(updated, include_key_field: false))

data/lib/better_auth/api_key/routes/verify_api_key.rb

@@ -9,7 +9,12 @@ module BetterAuth
         module_function
 
         def endpoint(config)
-          BetterAuth::Endpoint.new(path: "/api-key/verify", method: "POST") do |ctx|
+          BetterAuth::Endpoint.new(
+            path: "/api-key/verify",
+            method: "POST",
+            body_schema: ->(value) { value },
+            metadata: Routes.openapi_for(:verify_api_key)
+          ) do |ctx|
             body = BetterAuth::Plugins.normalize_hash(ctx.body)
             resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, body[:config_id])
             key = body[:key]
@@ -21,10 +26,13 @@ module BetterAuth
               )
             end
 
-            if resolved_config[:custom_api_key_validator].respond_to?(:call) && !resolved_config[:custom_api_key_validator].call({ctx: ctx, key: key})
+            validation_config = body[:config_id] ? resolved_config : config_for_key(ctx, key, config)
+            validation_config ||= resolved_config
+            validator = validation_config[:custom_api_key_validator]
+            if validator.respond_to?(:call) && !validator.call({ctx: ctx, key: key})
               ctx.json({valid: false, error: {message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "KEY_NOT_FOUND"}, key: nil})
             else
-              record = BetterAuth::Plugins.api_key_validate!(ctx, key, resolved_config, permissions: body[:permissions])
+              record = BetterAuth::Plugins.api_key_validate!(ctx, key, validation_config, permissions: body[:permissions])
               record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
               BetterAuth::Plugins.api_key_schedule_cleanup(ctx, record_config)
               ctx.json({valid: true, error: nil, key: BetterAuth::Plugins.api_key_public(record, include_key_field: false)})
@@ -37,6 +45,20 @@ module BetterAuth
             ctx.json({valid: false, error: {message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "INVALID_API_KEY"}, key: nil})
           end
         end
+
+        def config_for_key(ctx, key, config)
+          config.fetch(:configurations, [config]).each do |entry|
+            hashed = BetterAuth::Plugins.api_key_hash(key, entry)
+            record = BetterAuth::Plugins.api_key_find_by_hash(ctx, hashed, entry)
+            next unless record
+
+            record_config_id = BetterAuth::Plugins.api_key_record_config_id(record)
+            return entry if BetterAuth::Plugins.api_key_config_id_matches?(record_config_id, entry[:config_id])
+
+            return BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, record_config_id)
+          end
+          nil
+        end
       end
     end
   end

data/lib/better_auth/api_key/schema.rb

@@ -8,6 +8,7 @@ module BetterAuth
       def schema(config, custom_schema = nil)
         base = {
           apikey: {
+            model_name: "api_keys",
             fields: {
               configId: {type: "string", required: true, default_value: "default", index: true},
               name: {type: "string", required: false},

data/lib/better_auth/api_key/validation.rb

@@ -5,6 +5,13 @@ module BetterAuth
     module Validation
       module_function
 
+      USAGE_LOCK_STRIPE_COUNT = 256
+
+      def usage_lock_for(key)
+        @usage_lock_stripes ||= Array.new(USAGE_LOCK_STRIPE_COUNT) { Mutex.new }
+        @usage_lock_stripes[key.hash % USAGE_LOCK_STRIPE_COUNT]
+      end
+
       def validate_create_update!(body, config, create:, client:)
         name = body[:name]
         if create && config[:require_name] && name.to_s.empty?
@@ -68,25 +75,34 @@ module BetterAuth
 
       def validate_api_key!(ctx, key, config, permissions: nil)
         hashed = BetterAuth::APIKey::Keys.hash(key, config)
-        record = BetterAuth::APIKey::Adapter.find_by_hash(ctx, hashed, config)
-        raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless record
-        unless BetterAuth::APIKey::Routes.config_id_matches?(BetterAuth::APIKey::Types.record_config_id(record), config[:config_id])
-          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"])
-        end
-        raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_DISABLED"]) if record["enabled"] == false
-        if record["expiresAt"] && record["expiresAt"] <= Time.now
-          BetterAuth::APIKey::Adapter.schedule_record_delete(ctx, record, config)
-          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_EXPIRED"])
-        end
-        if record["remaining"].to_i <= 0 && !record["remaining"].nil? && record["refillAmount"].nil?
-          BetterAuth::APIKey::Adapter.schedule_record_delete(ctx, record, config)
-          raise BetterAuth::APIError.new("TOO_MANY_REQUESTS", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USAGE_EXCEEDED"])
-        end
+        usage_lock_for(hashed).synchronize do
+          record = BetterAuth::APIKey::Adapter.find_by_hash(ctx, hashed, config)
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless record
+          unless BetterAuth::APIKey::Routes.config_id_matches?(BetterAuth::APIKey::Types.record_config_id(record), config[:config_id])
+            raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"])
+          end
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_DISABLED"]) if record["enabled"] == false
+          if record["expiresAt"] && record["expiresAt"] <= Time.now
+            BetterAuth::APIKey::Adapter.schedule_record_delete(ctx, record, config)
+            raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_EXPIRED"])
+          end
+          if record["remaining"].to_i <= 0 && !record["remaining"].nil? && record["refillAmount"].nil?
+            BetterAuth::APIKey::Adapter.schedule_record_delete(ctx, record, config)
+            raise BetterAuth::APIError.new("TOO_MANY_REQUESTS", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USAGE_EXCEEDED"])
+          end
 
-        check_permissions!(record, permissions)
-        update = usage_update(record, config)
-        updated = BetterAuth::APIKey::Adapter.update_record(ctx, record, update, config, defer: true)
-        BetterAuth::APIKey::Adapter.migrate_legacy_metadata(ctx, updated || record.merge(update.transform_keys { |key_name| BetterAuth::Schema.storage_key(key_name) }), config)
+          check_permissions!(record, permissions)
+          update = usage_update(record, config)
+          updated = BetterAuth::APIKey::Adapter.update_record(ctx, record, update, config, defer: false)
+          unless updated
+            raise BetterAuth::APIError.new(
+              "INTERNAL_SERVER_ERROR",
+              message: BetterAuth::Plugins::API_KEY_ERROR_CODES["FAILED_TO_UPDATE_API_KEY"],
+              code: "FAILED_TO_UPDATE_API_KEY"
+            )
+          end
+          BetterAuth::APIKey::Adapter.migrate_legacy_metadata(ctx, updated || record.merge(update.transform_keys { |key_name| BetterAuth::Schema.storage_key(key_name) }), config)
+        end
       end
 
       def usage_update(record, config)

data/lib/better_auth/api_key/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module APIKey
-    VERSION = "0.8.0"
+    VERSION = "0.10.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-api-key
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: better_auth-mongodb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: better_auth-redis-storage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +121,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.83'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.83'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: standardrb
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +177,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tiny_tds
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 description: Adds API key creation, verification, management, quotas, metadata, and
   permissions for Better Auth Ruby. Includes storage modes. Also supports API-key-backed
   sessions. Better Auth Ruby is an independent modern authentication framework for
@@ -114,14 +226,14 @@ files:
 - lib/better_auth/api_key/validation.rb
 - lib/better_auth/api_key/version.rb
 - lib/better_auth/plugins/api_key.rb
-homepage: https://github.com/sebasxsala/better-auth
+homepage: https://github.com/sebasxsala/better-auth-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sebasxsala/better-auth
-  source_code_uri: https://github.com/sebasxsala/better-auth
-  changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth-api-key/CHANGELOG.md
-  bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
+  homepage_uri: https://github.com/sebasxsala/better-auth-rb
+  source_code_uri: https://github.com/sebasxsala/better-auth-rb
+  changelog_uri: https://github.com/sebasxsala/better-auth-rb/blob/main/packages/better_auth-api-key/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth-rb/issues
 rdoc_options: []
 require_paths:
 - lib