Rate Limit Configuration

The rate-limit.conf file configures request rate limits and progressive failure backoff for the Issuer2 and Verifier2 services, and for the unauthenticated superadmin bootstrap endpoint. This unified configuration file replaces the previous separate issuer2-rate-limit.conf and persistence-issuer2.conf files.

Configuration Sections

The file contains four main sections:

  1. persistence — Redis configuration for progressive failure backoff (shared between services)
  2. issuer2_* — Rate limits for Issuer2 OID4VCI endpoints
  3. verifier2_* — Rate limits for Verifier2 OID4VP endpoints
  4. superadmin_* — Rate limits for the superadmin bootstrap endpoint

Default Configuration

rate-limit.conf
# Persistence configuration for progressive failure backoff.
# Without Redis, only basic request-volume limits apply.
persistence {
  # Default: no Redis, failure backoff disabled
  # type = "memory"

  # Redis single-node example:
  # type = "redis"
  # nodes = [{ host = "redis", port = 6379 }]
  # user = "default"
  # password = "change-me"

  # Redis cluster example:
  # type = "redis-cluster"
  # nodes = [
  #   { host = "redis-node-1", port = 6379 },
  #   { host = "redis-node-2", port = 6379 },
  #   { host = "redis-node-3", port = 6379 }
  # ]
}

# Issuer2 OpenID4VCI rate limits
issuer2_token_endpoint {
  requestsPerMinute = 5
  failureWindowSeconds = 60
  failureThreshold = 5
  failureBlockSeconds = 300
}

issuer2_credential_endpoint {
  requestsPerMinute = 10
  failureWindowSeconds = 60
  failureThreshold = 5
  failureBlockSeconds = 300
}

# Verifier2 OpenID4VP rate limits
verifier2_request_endpoint {
  requestsPerMinute = 10
  failureWindowSeconds = 60
  failureThreshold = 5
  failureBlockSeconds = 300
}

verifier2_response_endpoint {
  requestsPerMinute = 5
  failureWindowSeconds = 60
  failureThreshold = 5
  failureBlockSeconds = 300
}

# Superadmin bootstrap rate limit
superadmin_create_by_token_endpoint {
  requestsPerMinute = 5
  failureWindowSeconds = 60
  failureThreshold = 5
  failureBlockSeconds = 300
}

Persistence Section

The persistence section configures Redis for progressive failure backoff. Without Redis, only basic Ktor request-volume limits apply.

FieldTypeDescription
typeString"memory" (default), "redis", or "redis-cluster"
nodesArrayList of Redis nodes with host and port
userStringOptional Redis username
passwordStringOptional Redis password

Endpoint Rate Limit Fields

Each endpoint section (issuer2_token_endpoint, issuer2_credential_endpoint, verifier2_request_endpoint, verifier2_response_endpoint, superadmin_create_by_token_endpoint) supports the following fields:

FieldTypeDefaultDescription
requestsPerMinuteIntegerVariesMaximum requests per minute per service/endpoint/IP
failureWindowSecondsInteger60Time window for counting failures
failureThresholdInteger5Failures required to create a block
failureBlockSecondsInteger300Duration of the temporary block

Default Rate Limits

EndpointDefault requestsPerMinute
issuer2_token_endpoint5
issuer2_credential_endpoint10
verifier2_request_endpoint10
verifier2_response_endpoint5
superadmin_create_by_token_endpoint5

Superadmin Bootstrap Endpoint

POST /v1/superadmin/create-by-token is unauthenticated, so it is throttled per source IP rather than per service target. Exceeding the limit — or tripping the failure backoff when Redis is configured — returns 429 with a Retry-After header.

Last updated on September 3, 2026