How to Configure API Rate Limit?

Protect your ServiceOps instance from abuse and ensure system stability by implementing robust API rate limiting.

The API Rate Limiting feature in ServiceOps helps control the number of API requests made within defined time intervals. This prevents abuse, ensures fair usage, and protects system stability. Rate limiting is essential for maintaining optimal performance and preventing resource exhaustion in production environments.

API rate limiting provides several benefits:

Prevents API abuse and malicious attacks
Ensures fair resource allocation among users
Protects system stability during high traffic periods
Controls costs by limiting excessive API usage
Improves overall system performance by managing request load

Prerequisites

Before configuring API rate limits, ensure you have:

Administrative access to the ServiceOps server
Technician role permissions for applying configuration changes
Understanding of your API usage patterns and requirements
Backup of current configuration files
Access to ServiceOps configuration directories

Configuration Files

Rate limiting is configured using YAML files in two separate services:

Main Service Configuration Files

Default Configuration: /opt/flotomate/main-server/config/flotomate_rate_limit.yaml
Custom Configuration: /opt/flotomate/main-server/config/flotomate_rate_limit_custom.yaml

Analytics Service Configuration Files

Default Configuration: /opt/flotomate/cm-analytics/config/flotomate_rate_limit.yaml
Custom Configuration: /opt/flotomate/cm-analytics/config/flotomate_rate_limit_custom.yaml

Best Practice

Always use custom configuration files (flotomate_rate_limit_custom.yaml) to avoid losing changes during system updates. Custom files override default settings without modifying core files.

Basic Configuration Parameters

The rate limiting system uses a token bucket algorithm with the following key parameters:

Global Configuration Parameters

Parameter	Description	Default Value	Example
`enabled`	Enables/disables global rate limiting	`true`	`enabled: true`
`apply-default-rate-limiting`	Applies default limits when no group matches	`true`	`apply-default-rate-limiting: true`
`token-cache-timeout-minutes`	Token cache duration in minutes	`30`	`token-cache-timeout-minutes: 30`
`refill-rate`	Tokens added every refill interval	`20`	`refill-rate: 20`
`refill-interval`	Interval between token refills (seconds)	`1`	`refill-interval: 1`
`bucket-capacity`	Maximum tokens a bucket can hold	`30`	`bucket-capacity: 30`
`initial-bucket-capacity`	Initial tokens in a new bucket	`30`	`initial-bucket-capacity: 30`

Excluding Routes from Rate Limiting

Use the excluded-routes section to bypass rate limiting for specific endpoints that require unrestricted access:

excluded-routes:
  - path: /api/public/organization
  - path: /api/public/ssoconfig/details
  - path: /api/public/supportPortalConfig
  - path: /cm-analytics/config
    methods: [GET]

Excluded Routes Parameters

path: URL path to exclude (supports Ant-style wildcards like /**)
methods: Optional list of HTTP methods to exclude (e.g., [GET, POST, PUT, DELETE])

tip

Path Matching: Use Ant-style wildcards for flexible path matching:

/** matches any number of path segments
/* matches exactly one path segment
? matches exactly one character

Creating API Groups

API groups apply specific rate limits to sets of authenticated routes using tokens from the Authorization header. This allows different rate limits for different types of API operations.

API Group Configuration Example

api-groups:
  - name: high-volume
    enabled: true
    routes:
      - path: /api/search/**
        methods: [GET, POST]
      - path: /api/list/**
        methods: [GET]
    bucket-capacity: 100
    refill-rate: 50
    refill-interval: 1
    initial-bucket-capacity: 100
    
  - name: low-volume
    enabled: true
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10

API Group Parameters

Parameter	Description	Required	Example
`name`	Unique name for the group	Yes	`name: high-volume`
`enabled`	Enables/disables rate limiting for this group	Yes	`enabled: true`
`routes`	List of routes to apply rate limits to	Yes	See route configuration below
`bucket-capacity`	Maximum tokens available for this group	Yes	`bucket-capacity: 100`
`refill-rate`	Tokens added per refill interval	Yes	`refill-rate: 50`
`refill-interval`	Time interval between token refills (seconds)	Yes	`refill-interval: 1`
`initial-bucket-capacity`	Initial tokens available for the group	Yes	`initial-bucket-capacity: 100`

Route Configuration

Each route in an API group can specify:

routes:
  - path: /api/search/**
    methods: [GET, POST]

path: URL path to restrict (supports wildcards)
methods: List of HTTP methods to apply rate limits to

Creating Global API Groups

Global API groups allow you to apply rate limits to endpoints that may not have authentication headers or require special handling. They are particularly useful for:

Public endpoints that don't require authentication
Sensitive operations that need stricter controls
Shared rate limits across multiple users
Preventing abuse of public APIs

Global API Group Configuration Example

enabled: true
apply-default-rate-limiting: false
refill-rate: 20
refill-interval: 1
bucket-capacity: 30
token-cache-timeout-minutes: 30
initial-bucket-capacity: 30

excluded-routes:
  - path: /api/public/organization
  - path: /api/public/ssoconfig/details
  - path: /api/public/supportPortalConfig

api-groups:
  - name: high-volume
    enabled: true
    routes:
      - path: /api/search/**
        methods: [GET, POST]
      - path: /api/list/**
        methods: [GET]
    bucket-capacity: 100
    refill-rate: 50
    refill-interval: 1
    initial-bucket-capacity: 100
    
  - name: low-volume
    enabled: true
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10

global-api-groups:
  - name: public-api
    enabled: true
    token: public_api_token_xyz
    routes:
      - path: /api/public/**
        methods: [GET, POST]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10
    
  - name: sensitive-operations
    enabled: true
    token: sensitive_ops_token_abc
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 3
    refill-rate: 1
    refill-interval: 5
    initial-bucket-capacity: 3

Global API Group Parameters

Parameter	Description	Required	Example
`name`	Unique identifier for the group	Yes	`name: public-api`
`enabled`	Enables/disables rate limiting for this group	Yes	`enabled: true`
`token`	Required token for rate limiting this group	Yes	`token: public_api_token_xyz`
`routes`	List of routes to apply rate limits to	Yes	See route configuration above
`bucket-capacity`	Maximum tokens available for this group	Yes	`bucket-capacity: 10`
`refill-rate`	Tokens added per refill interval	Yes	`refill-rate: 5`
`refill-interval`	Time interval between token refills (seconds)	Yes	`refill-interval: 1`
`initial-bucket-capacity`	Initial tokens available for the group	Yes	`initial-bucket-capacity: 10`

danger

Token Uniqueness: The token parameter must be unique across all global API groups. Reusing tokens can cause unexpected behavior.

Complete Configuration Example

Here's a complete example of a custom rate limit configuration file:

# Global rate limiting settings
enabled: true
apply-default-rate-limiting: false
refill-rate: 20
refill-interval: 1
bucket-capacity: 30
token-cache-timeout-minutes: 30
initial-bucket-capacity: 30

# Routes excluded from rate limiting
excluded-routes:
  - path: /api/public/organization
  - path: /api/public/ssoconfig/details
  - path: /api/public/supportPortalConfig
  - path: /cm-analytics/config
    methods: [GET]

# API groups for authenticated routes
api-groups:
  - name: high-volume
    enabled: true
    routes:
      - path: /api/search/**
        methods: [GET, POST]
      - path: /api/list/**
        methods: [GET]
    bucket-capacity: 100
    refill-rate: 50
    refill-interval: 1
    initial-bucket-capacity: 100
    
  - name: low-volume
    enabled: true
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10

# Global API groups for unauthenticated routes
global-api-groups:
  - name: public-api
    enabled: true
    token: public_api_token_xyz
    routes:
      - path: /api/public/**
        methods: [GET, POST]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10
    
  - name: sensitive-operations
    enabled: true
    token: sensitive_ops_token_abc
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 3
    refill-rate: 1
    refill-interval: 5
    initial-bucket-capacity: 3

Special Client Handling

Rate limits are automatically skipped for the following internal services to ensure system functionality:

Plugin server client
Analytics service
Main server service

These services are considered trusted and bypass rate limiting to prevent internal system issues.

Rate Limit Headers

When rate limiting is applied, the following headers are included in API responses to help clients manage their request rates:

Header	Description	Example
`X-RateLimit-Limit`	Maximum number of requests allowed	`X-RateLimit-Limit: 100`
`X-RateLimit-Remaining`	Number of requests remaining in current window	`X-RateLimit-Remaining: 85`
`X-RateLimit-Reset`	Time (in milliseconds) until rate limit resets	`X-RateLimit-Reset: 5000`

Prerequisites​

Configuration Files​

Basic Configuration Parameters​

Excluding Routes from Rate Limiting​

Creating API Groups​

Creating Global API Groups​

Complete Configuration Example​

Special Client Handling​

Rate Limit Headers​

Related Topics​