API Reference

Authentication

When authentication is enabled (RLAAS_AUTH_ENABLED=true), all requests except exempt paths must include credentials.

API Key Mode

Set RLAAS_AUTH_MODE=apikey and provide keys via RLAAS_AUTH_API_KEYS.

X-Api-Key: your-secret-key

Alternatively, pass the key as a Bearer token:

Authorization: Bearer your-secret-key

JWT Mode

Set RLAAS_AUTH_MODE=jwt and provide the HMAC secret via RLAAS_AUTH_JWT_SECRET.

Authorization: Bearer <HS256-signed-JWT>

Mutating endpoints (POST, PUT, DELETE) require the configured admin role claim. Read endpoints accept the read-only role.

Exempt Paths

/healthz and /readyz are exempt by default so that Kubernetes probes work without credentials.

Operational Endpoints

GET /healthz

Liveness probe. Returns 200 OK with body ok when the process is alive.

GET /readyz

Readiness probe. Returns 200 OK with body ok after all routes are registered and the server is ready to accept traffic. Returns 503 Service Unavailable during startup and shutdown drain.

GET /metrics

Prometheus text exposition format. Exposes counters for decisions (total, allowed, denied, shadow), latency histogram, policy cache hit/miss, counter store errors, and per-tenant/policy dimensional counters.

Decision APIs

Core endpoints for rate-limit evaluation and concurrency control.

POST /rlaas/v1/check

Evaluate a rate-limit decision for a request context.

Request Body

{
  "request_id": "req-1",
  "org_id": "acme",
  "tenant_id": "retail",
  "signal_type": "http",
  "operation": "charge",
  "endpoint": "/v1/charge",
  "method": "POST",
  "user_id": "u1",
  "tags": { "env": "production" }
}

Response (200 OK)

{
  "allowed": true,
  "action": "allow",
  "reason": "within_limit",
  "matched_policy_id": "payments-limit",
  "remaining": 99,
  "retry_after": 0,
  "shadow_mode": false
}

POST /rlaas/v1/acquire

Acquire a concurrency lease. Use with concurrency limiter algorithm.

Request Body

{
  "request_id": "req-2",
  "org_id": "acme",
  "signal_type": "http",
  "operation": "heavy-query",
  "user_id": "u1"
}

Response

{
  "allowed": true,
  "action": "allow",
  "reason": "lease_acquired",
  "remaining": 4
}

POST /rlaas/v1/release

Release a previously acquired concurrency lease.

Request Body

{
  "request_id": "req-2",
  "org_id": "acme",
  "signal_type": "http",
  "operation": "heavy-query",
  "user_id": "u1"
}

Response

{
  "allowed": true,
  "action": "allow",
  "reason": "lease_released"
}

Policy CRUD

GET /rlaas/v1/policies

List all policies.

Response

[
  {
    "policy_id": "payments-limit",
    "name": "Payments limit",
    "enabled": true,
    "priority": 100,
    "scope": { "org_id": "acme", "signal_type": "http", "operation": "charge" },
    "algorithm": { "type": "fixed_window", "limit": 100, "window": "1m" },
    "action": "deny",
    "failure_mode": "fail_open",
    "enforcement_mode": "enforce",
    "rollout_percent": 100
  }
]

POST /rlaas/v1/policies

Create a new policy.

Request Body

{
  "policy_id": "payments-limit",
  "name": "Payments limit",
  "enabled": true,
  "priority": 100,
  "scope": {
    "org_id": "acme",
    "signal_type": "http",
    "operation": "charge"
  },
  "algorithm": {
    "type": "fixed_window",
    "limit": 100,
    "window": "1m"
  },
  "action": "deny",
  "failure_mode": "fail_open",
  "enforcement_mode": "enforce",
  "rollout_percent": 100
}

GET /rlaas/v1/policies/{id}

Get a specific policy by ID.

PUT /rlaas/v1/policies/{id}

Update an existing policy. The full policy body is required.

DELETE /rlaas/v1/policies/{id}

Delete a policy by ID.

Policy Lifecycle APIs

POST /rlaas/v1/policies/validate

Validate a policy definition before deployment.

Request

{
  "name": "Validation sample",
  "enabled": true,
  "scope": { "signal_type": "http", "operation": "charge" },
  "algorithm": { "type": "fixed_window", "limit": 10, "window": "1m" },
  "action": "deny",
  "rollout_percent": 50
}

Response

{ "valid": true }

POST /rlaas/v1/policies/{id}/rollout

Update the rollout percentage for gradual enforcement.

{ "rollout_percent": 25 }

POST /rlaas/v1/policies/{id}/rollback

Roll back to a specific previous version.

{ "version": 1 }

GET /rlaas/v1/policies/{id}/audit

Get the audit trail for a policy — all changes with timestamps, action types, old/new values.

GET /rlaas/v1/policies/{id}/versions

Get all historical versions of a policy for review or rollback.

Analytics

GET /rlaas/v1/analytics/summary

Get a summary of decision events with tag aggregation.

Query Parameters

Example

curl http://localhost:8080/rlaas/v1/analytics/summary?top=5

Sidecar / Agent Endpoints

Default port: :18080

gRPC Service

Proto definition: api/proto/rlaas.proto  |  Default port: :9090

service RateLimitService {
  rpc CheckLimit(CheckLimitRequest)  returns (CheckLimitResponse);
  rpc Acquire(AcquireRequest)        returns (AcquireResponse);
  rpc Release(ReleaseRequest)        returns (ReleaseResponse);
}

The gRPC service exposes the same decision logic as the HTTP API. Generate client stubs from the proto file for any language.

RequestContext Object

Sent as the body of decision API calls. All fields are optional except as noted.

Decision Object

Returned by decision API calls.

Policy Object

Used for policy CRUD operations.

Error Format

All error responses return a JSON body with a descriptive message:

{
  "error": "policy not found",
  "status": 404
}