Appcircle Rate Limiting

Overview

Appcircle applies rate limiting at two layers to protect APIs from abuse and ensure fair usage across users and organizations.

1. Global Layer (Front Layer): Enforces global IP-based rate limiting before requests reach the internal gateway.

2. Gateway Layer (Ocelot): Applies fine-grained rate limiting per endpoint based on user, organization, or IP.

This layered approach ensures both system-wide stability and flexible control at the endpoint level.

%%{init: {
  'themeVariables': {
    'fontFamily': 'Inter, Arial, Helvetica, sans-serif',
    'fontSize': '18px',
    'primaryColor': '#f4fafd',
    'edgeLabelBackground':'#eaf4fd',
    'secondaryColor': '#eefcff',
    'tertiaryColor': '#c3ffee',
    'primaryBorderColor': '#278beb',
    'nodeTextColor': '#222',
    'lineColor': '#10b981',
    'shadow1': '2px 2px 8px #d7eafc'
  },
  'flowchart': {
    'curve': 'monotoneX'
  }
}}%%
flowchart LR
    A("🌐 Incoming Traffic<br/>(External Requests)")
    subgraph acn["Appcircle Network"]
      direction LR
      B("🧱 Global Layer<br/>Global IP Rate Limit")
      C("🔐 Authentication<br/>Identity & Token Validation")
      D("🚪 Gateway Layer<br/>User/Org/Ip Rate Limit & Routing")
      E("🧩 Internal Services<br/>(Appcircle Modules)")
    end


    A --> B
    B --> C
    C --> D
    D --> E

    %% Custom styling for nodes to match Appcircle brand colors
    classDef inbound fill:#f4fafd,stroke:#278beb,stroke-width:2.5px,color:#176db1;
    classDef acn_nodes fill:#eefcff,stroke:#278beb,stroke-width:2.5px,color:#1d4e89;
    classDef out_nodes fill:#e8fcf5,stroke:#10b981,stroke-width:2.5px,color:#065f46;

    class A inbound
    class B,C,D acn_nodes
    class E out_nodes

    %% Subgraph styling: subtle blue/gray background
    style acn fill:#eaf4fd,stroke:#60b5f9,stroke-width:2px

Enabling Rate Limiting

Rate limiting on the Gateway Layer (Ocelot) can be enabled globally using the following environment variable:

ASPNETCORE_RATE_LIMITING_ENABLED="true"

When enabled, each endpoint can specify a rate-limiting policy type—User, Organization, or IP—based on the desired level of isolation.

Default Policies

User-Based Rate Limits

Policy	Window	Max Requests	Retry After	Claim
API_HIGH_USER	1 minute	300	5 seconds	sub
API_MEDIUM_USER	1 minute	200	10 seconds	sub
API_LOW_USER	1 minute	100	30 seconds	sub

Organization-Based Rate Limits

Policy	Window	Max Requests	Retry After	Claim
API_HIGH_ORG	1 minute	3000	5 seconds	organization_id
API_MEDIUM_ORG	1 minute	2000	10 seconds	organization_id
API_LOW_ORG	1 minute	1000	30 seconds	organization_id

IP-Based Rate Limits

Policy	Window	Max Requests	Retry After	Header
API_HIGH_IP	1 minute	200	15 seconds	X-Forwarded-For
API_LOW_IP	1 minute	50	20 seconds	X-Forwarded-For

Note: These policy definitions represent the default configuration. When defined under the Ocelot configuration in the repository, their values can be modified programmatically at runtime or through deployment-specific overrides. This allows teams to fine-tune rate limits based on environment (e.g., dev, prep, prod) or service-level requirements.

Behavior and Policy Assignment

Each API endpoint can be associated with a predefined policy depending on its purpose:

• GET endpoints → higher request allowance
• UPDATE / CREATE endpoints → moderate limits
• DELETE endpoints → most restrictive

Policies are selected in Ocelot based on the endpoint’s type and claim context (User or Organization).

Global IP-Based Rate Limiting

This configuration enforces a global IP rate limit across all endpoints.

ASPNETCORE_RATE_LIMITING_GLOBAL_IP_ENABLED="true"
ASPNETCORE_RATE_LIMITING_GLOBAL_IP_POLICY="enabled=true, window=1m, maxRequests=600, retryAfter=20s, header=X-Forwarded-For"

Note: Ensure that the X-Forwarded-For header is correctly passed through the load balancer or ingress controller so that the real client IP is used for rate limiting.

Cloud Environment Behavior

In cloud deployments:

• The WAF (Web Application Firewall) handles global IP throttling.
• Therefore, both global IP rate limiting and Ocelot IP-based rate limiting are disabled.
• Ocelot enforces rate limits only by User and Organization.

This ensures compatibility with external WAF configurations while maintaining fine-grained control internally.