Api Rate Abuse in Hanami with Api Keys

Rate abuse occurs when an attacker sends a high volume of requests to an endpoint, consuming server resources and potentially degrading availability. In Hanami, a Ruby web framework, this risk is compounded when endpoints are protected only by API keys without additional rate controls.

An API key is a bearer credential typically passed in an HTTP header such as X-API-Key. If an endpoint relies solely on key validation and lacks per-key or per-client rate limits, a single compromised or leaked key allows unbounded request volume. Unlike authenticated user sessions, API keys often represent service-to-service access and are long-lived, making them attractive targets for abuse.

For example, consider a Hanami endpoint that provides public data but still requires an API key for access. An attacker who obtains the key can script repeated calls to data-intensive actions (search, export, or aggregation endpoints). Because the application does not enforce throttling, the server may experience high CPU, memory, or database connection pressure. This can lead to denial of service for legitimate users. In a black-box scan, such as those performed by middleBrick, missing rate-limiting controls are flagged as a finding under the Rate Limiting category, with a note that unauthenticated attack surface testing revealed no per-key or per-IP throttling.

When API keys are used without rotation policies or revocation mechanisms, the exposure window is extended. middleBrick’s authentication checks verify whether keys are embedded in URLs or exposed in client-side code, but they also highlight that rate-limiting must be applied at the key level to prevent abuse. Without explicit limits, an attacker can conduct low-and-slow campaigns that evade simple anomaly detection while still exhausting resources.

In practice, an API key should be treated as a long-lived secret that grants access to specific operations. If rate limiting is not enforced per key, the security posture relies entirely on the secrecy of the key. Once secrecy is compromised, the attacker gains persistent access until the key is rotated. middleBrick’s scan includes Rate Limiting as one of its 12 parallel checks and surfaces findings that show whether per-key throttling is absent, helping teams prioritize fixes before abuse occurs.

To mitigate rate abuse when using API keys in Hanami, implement per-key rate limiting combined with secure key management. Below are concrete steps and code examples.

1. Use a rate-limiting library with key-based buckets

Integrate a rate-limiting library such as rack-attack to enforce limits per API key. Configure rules that track requests by a normalized key header and reject excess requests with a 429 Too Many Requests response.

# config/initializers/rack_attack.rb
class Rack::Attack
  # Throttle requests per API key
  throttle("api/key", limit: 300, period: 60) do |req|
    # Extract API key from headers
    req.get_header("HTTP_X_API_KEY")
  end

  # Custom response when rate limit is exceeded
  self.throttled_response = lambda do |env|
    [
      429,
      { "Content-Type" => "application/json" },
      [{ error: "Rate limit exceeded. Try again later." }.to_json]
    ]
  end
end

2. Validate and rotate API keys securely

Store API keys encrypted and rotate them periodically. Avoid embedding keys in URLs or JavaScript bundles. In Hanami, you can define a custom repository to manage key verification and metadata such as rate limits.

# lib/api_key_repository.rb
class ApiKeyRepository
  def self.verify(key)
    # Fetch key record from the database, ensuring it is active and not expired
    record = Hanami::Model.query(:api_keys).where(key_hash: ApiKeyRepository.hash_key(key)).first
    raise "Invalid key" unless record
    raise "Key disabled" unless record.active?
    record
  end

  def self.hash_key(key)
    Digest::SHA256.hexdigest(key)
  end
end

3. Apply key-based limits within the application layer

For finer control, enforce limits inside your Hanami actions or policies by tracking usage in a cache store such as Redis. This complements rack-attack by allowing dynamic adjustments per key.

# app/actions/items/search.rb
class Items::Search
  include Hanami::Action

  def call(params)
    api_key = env["HTTP_X_API_KEY"]
    usage_key = "rate_limit:#{api_key}"
    current = $redis.get(usage_key).to_i
    limit = 100

    if current >= limit
      raise Hanami::Action::Forbidden, { error: "Quota exceeded for this API key" }
    end

    $redis.incr(usage_key)
    $redis.expire(usage_key, 3600) unless $redis.ttl(usage_key) > 0

    # proceed with business logic
    Items::Search.new.call(params)
  end
end

4. Combine with other security checks

Ensure API keys are not logged in plaintext and are transmitted only over TLS. middleBrick’s Authentication and Encryption checks help identify weak handling of keys and missing transport protections. Use the CLI to verify your setup: middlebrick scan <url> to detect misconfigurations before deployment.