- Updated: March 18, 2026
- 5 min read
Securing and Enforcing Rate‑Limiting for the OpenClaw Rating API Edge Token Bucket with OPA
# Securing and Enforcing Rate‑Limiting for the OpenClaw Rating API Edge Token Bucket with Open Policy Agent (OPA)
**Author:** UBOS Team
—
## Introduction
The OpenClaw Rating API uses an **Edge Token Bucket** to protect its endpoints from abuse. While the token bucket provides a basic throttling mechanism, adding **Open Policy Agent (OPA)** gives you fine‑grained, declarative control over who can call the API, how many requests they may make, and under what conditions.
In this article we walk through:
1. Writing an OPA policy that enforces rate‑limiting rules.
2. Integrating the policy with the OpenClaw Edge Token Bucket.
3. Testing the enforcement pipeline.
4. Best‑practice recommendations for production deployments.
> **Note:** For a complete walkthrough of hosting OpenClaw on UBOS, see the internal guide: .
—
## 1. OPA Policy Creation
Create a file called `rate_limit.rego` in your policy repository:
rego
package openclaw.ratelimit
# Default deny – if no rule matches the request is blocked.
default allow = false
# Configuration – you can externalise these values to a ConfigMap or DB.
max_requests_per_minute = 60
burst_capacity = 10
# Helper to extract the API key from the request header.
api_key = input.request.headers[“x-api-key”]
# Rate‑limit state is stored in OPA’s built‑in cache (or an external KV store).
rate_key = sprintf(“%s:%s”, [api_key, input.request.path])
# Allow if the request does not exceed the token bucket limits.
allow {
not over_limit
}
# Check the token bucket – OPA’s cache stores the remaining tokens and the reset timestamp.
over_limit {
bucket := data.ratelimit[rate_key]
bucket.tokens time.now_ns()
}
# Update the bucket after a successful request (side‑effect via OPA’s `set` builtin).
update_bucket {
bucket := data.ratelimit[rate_key]
new_tokens := bucket.tokens – 1
new_reset := time.now_ns() + (60 * 1000000000) # 1 minute in nanoseconds
set(data.ratelimit[rate_key], {“tokens”: new_tokens, “reset”: new_reset})
}
*Explanation*
– **`max_requests_per_minute`** and **`burst_capacity`** define the token bucket limits.
– The policy extracts the API key, builds a unique rate‑limit key, and checks the bucket.
– If the bucket is exhausted, `allow` is `false` and the request is rejected.
– On a successful request, `update_bucket` decrements the token count.
—
## 2. Integration with the Edge Token Bucket
1. **Deploy OPA** as a sidecar or as a centralized policy decision point (PDP).
2. **Configure OpenClaw** to call OPA before the token bucket logic:
– Add a middleware hook that sends the incoming request (method, path, headers) to OPA’s `/v1/data/openclaw/ratelimit/allow` endpoint.
– If OPA returns `{ “result”: true }`, proceed to the token bucket check; otherwise return `429 Too Many Requests`.
3. **Synchronise state**:
– Use OPA’s built‑in cache or an external Redis store to share bucket state across multiple instances of the API.
– Ensure the cache TTL matches the bucket reset interval.
Sample OpenClaw middleware (pseudo‑code):
go
func RateLimitMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Call OPA
decision, err := opaClient.Decide(r)
if err != nil || !decision.Allow {
http.Error(w, “Rate limit exceeded”, http.StatusTooManyRequests)
return
}
// Continue to Edge Token Bucket logic
next.ServeHTTP(w, r)
})
}
—
## 3. Testing the Enforcement Pipeline
### Unit Tests (OPA)
rego
test_allow_when_tokens_available {
data.ratelimit[“key1:/rate”] = {“tokens”: 5, “reset”: 0}
input = {“request”: {“headers”: {“x-api-key”: “key1”}, “path”: “/rate”}}
allow
}
test_deny_when_no_tokens {
data.ratelimit[“key2:/rate”] = {“tokens”: 0, “reset”: time.now_ns() + 30*1000000000}
input = {“request”: {“headers”: {“x-api-key”: “key2”}, “path”: “/rate”}}
not allow
}
### End‑to‑End Tests (Postman / curl)
bash
# First request – should succeed
curl -H “x-api-key: dev‑key” https://api.ubos.tech/openclaw/rate
# 61st request within a minute – should receive 429
for i in {1..61}; do curl -s -o /dev/null -w “%{http_code}\n” -H “x-api-key: dev‑key” https://api.ubos.tech/openclaw/rate; done
—
## 4. Best‑Practice Recommendations
| Recommendation | Why |
|—————-|—–|
| **Separate policy store** – keep OPA policies in a Git‑ops repository and reload on change. | Enables version control and auditability. |
| **Use a distributed cache** (Redis, Memcached) for token bucket state. | Guarantees consistent limits across multiple API replicas. |
| **Rate‑limit per API key and endpoint** – avoid a single key exhausting the bucket for all endpoints. | Provides granular control and prevents noisy‑neighbor problems. |
| **Expose metrics** (Prometheus) for OPA decisions and bucket usage. | Allows you to monitor health and tune limits. |
| **Graceful fallback** – if OPA is unavailable, decide whether to allow traffic (fail‑open) or block (fail‑closed) based on SLA. |
| **Secure OPA communication** – use mTLS between OpenClaw and OPA. |
—
## Conclusion
By combining **Open Policy Agent** with the existing **Edge Token Bucket**, you gain a powerful, declarative way to enforce rate‑limiting policies that are easy to audit, version, and extend. The approach scales horizontally, integrates cleanly with Kubernetes deployments, and gives developers the flexibility to adjust limits without touching application code.
For the full step‑by‑step guide on hosting OpenClaw on UBOS, visit the internal documentation: .
—
*Published by the UBOS Team*