API product

A function owner can offer the API behind their gateway to other people: every consumer gets API keys, every key or consumer gets rate limits and quotas, and RunR measures each consumer's calls — how many were let through or refused, and what the function answered: status, latency, errors and bytes. RunR does not sell or invoice anything. An external system reads the usage through the API or receives it as signed webhook events, and bills the consumers itself.

• Concepts
• How it works
• Routes: public, API key, JWT
• Consumers
• API keys
• Plans
• Calling a protected route
• When gateway-auth is not ready
• Usage
• Usage events
• Only through the gateway
• Custom domain
• Developer page
• Permissions
• API
• CLI and MCP
• Region requirements and operation
• Limits of this version

Concepts#

A route may lead to a global project from a gateway in any of the project's regions: the gateway hands requests to that region's copy. "Only through the gateway" is refused for global projects (it would close their global host name).

How it works#

caller ──HTTPS──▶ region Traefik ── gateway IngressRoute gw-<id>
                   │  route /orders (auth: key)
                   │    1. rateLimit per client IP (optional, the gateway's)
                   │    2. forwardAuth ──▶ runr-gateway-auth /auth/<route>   ─┐ 401 / 403 / 429
                   │    3. stripPrefix, Host rewrite                         │ back to the caller
                   ▼                                                         │ 200: let through
                 runr-gateway-auth-proxy (metering) ◀── X-Runr-Consumer, X-Runr-Key, ticket
                   │  status, latency and bytes of the answer
                   ▼
                 region Traefik (web) ──▶ project (Knative Service)

runr-gateway-auth ── every 10 s: GET  /api/internal/gateway-auth/<region>/config (ETag, 304)
                  ── every 30 s: POST /api/internal/gateway-auth/<region>/usage
                  ── counters:   the region's Redis (or the pod's memory without Redis)

• The region's gateway-auth service (ghcr.io/brf-tech/runr/gateway-auth, source in runtime/gateway-auth) runs in the region's project namespace. RunR installs it with the first key or JWT route of the region and updates it with region:reconcile. One service serves every organization's gateways in the region.
• Traefik asks the service before every call of a key or JWT route (Traefik forwardAuth, Middleware gw-auth-<route>). The service checks the key or token, the consumer, the key's scopes and the plan. It answers 200 to let the call through, or 401, 403 or 429, which go back to the caller.
• The service never gets a key from RunR. It gets the SHA-256 hash of each usable key, and hashes what a caller sends. Revoked and expired keys are left out.
• The service fetches changes every SYNC_SECONDS (default 10) with an ETag. RunR answers 304 until a key, consumer, plan or route changes. A revoked key stops working within that interval.
• Each pod counts every decision and reports the counts to RunR every 30 seconds. RunR adds them to hourly rows and applies a report once (by its batch id), also when it is sent again.
• The calls a key or JWT route lets through then pass the service's metering proxy (Service runr-gateway-auth-proxy), which hands them on unchanged — Host, path, headers and body, streamed, WebSockets and server-sent events included — to the region Traefik, where the route's project answers as before. It records what the function answered under the consumer, key and route the check decided on: the status class, the latency until the answer started, the bytes of request and answer, and calls that got no answer (Usage). The check hands the proxy a signed ticket of its decision (X-Runr-Gateway-Ticket, valid 60 seconds, keyed with the region's gateway-auth token); the proxy serves nothing without one (403 not_through_gateway), so a pod in the cluster can neither reach a function past its route's check nor count calls for a consumer, and the function never sees the ticket.
• A route of a project in access mode allowlist or "only through the gateway" has no public route on web: its rule names the project's own service in X-Runr-Gateway-Upstream (a value derived from the route and RunR's application key), which only the gateway's upstream IngressRoute gw-<id>-upstream matches. The client's address is still checked on the first hop.
• A route goes through the proxy once a pod of it is ready and no pod of an earlier image answers checks (an upgrade's rollout). Until then its calls go to the project directly, checked and counted but not measured, and the health job moves them onto the proxy within a minute (When gateway-auth is not ready).
• Counters for the limits are kept in the region's Redis (the queue triggers' Redis, regions.md), shared by the service's pods (2 by default). A region without Redis runs one pod that counts in memory, and its counters start over when the pod restarts. When Redis does not answer, the pod counts in memory and does not refuse every call.
• Key and JWT routes fail closed: while the service is not installed or not ready, they answer 503 auth_unavailable and never reach the function unchecked (When gateway-auth is not ready).

Routes#

A route is added in the console (Build & Run → API gateways → Routes → Add route: the project, the environment, the path, its authentication) or with POST /api/gateways/{gateway}/routes {"project_id": "…", "environment": "staging", "path": "/staging", "methods": ["GET"], "auth_mode": "key"}. Without environment (or with production) the route leads to the project's own workload, which then uses the gateway endpoint (endpoint_type: gateway); with one it leads to that environment's Knative Service <slug>-<name>. The gateway must be in the region the project or environment runs in (422 otherwise), a path is used once per gateway (422 path, on a change of the path too), and a project environment has one route. POST /api/gateways {"knative_region_id": "…"} gives you your gateway in a region where you have none yet (the console: Gateway in another region), e.g. for an environment that runs elsewhere than its project. Removing a route (DELETE /api/gateways/{gateway}/routes/{route}, the console's trash icon) syncs the gateway without it; deleting an environment or a project removes its routes.

A new route takes its authentication with it: auth_mode, jwt and gateway_only in the POST, validated as on a change. A key or JWT route reaches the region with its check in front of it — the forwardAuth Middleware is applied before the IngressRoute that references it — so it is never public, not even for a moment; the console, runr gateway routes add --auth, the MCP tool gateway_route_add and Terraform's runr_gateway_route all create it in one call. The answers of POST and PATCH are the route as the gateway shows it (url, auth_mode, jwt, gateway_only, its project and environment), like the routes of GET /api/gateways/{gateway}.

Authentication is changed per route in the console (Build & Run → API gateways → Routes), through PATCH /api/gateways/{gateway}/routes/{route} or runr gateway routes set.

JWT settings of a route (jwt object):

What the function receives on a call that was let through:

A caller cannot set these headers itself, because Traefik removes them from the request before it copies the service's answer. On key routes X-Api-Key and Authorization are removed as well, so the function never sees the key. On JWT routes the function keeps Authorization and can read the token's other claims.

Consumers#

curl -X POST "$RUNR/api/api-consumers" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"gateway_id": "01JG…", "name": "Acme Ltd", "email": "api@acme.example", "external_id": "CUST-1042", "plan_id": "01JP…"}'

Deleting a consumer deletes its keys. Its usage stays in the reports.

API keys#

curl -X POST "$RUNR/api/api-consumers/01JC…/keys" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "production", "scopes": [{"route_id": "01JR…", "methods": ["GET"]}], "expires_at": "2027-01-01T00:00:00Z"}'
# → 201 {"data": {"id": "01JK…", "prefix": "rk_Hk2v9QzL", "status": "active", …, "key": "rk_Hk2v9QzL…"}}

• A key is rk_ followed by 43 random letters and digits (about 256 bits). It is in the answer that creates or rotates it, and nowhere else. RunR keeps its SHA-256 hash and the first 11 characters (prefix) to tell keys apart. Keys are not written to the audit log or to logs; the audit keeps the key's id and prefix.
• scopes: [{route_id, methods}] limits the key to these routes of the consumer's gateway (all gateways of the organization for an organization consumer). methods limits it to some methods; leave it out for every method. Leave scopes out for every route.
• plan_id gives the key a plan of its own. Its limits are then counted for this key alone, not for the consumer.
• Rotation: POST /api/api-keys/{key}/rotate creates a key with the same scopes, plan and expiry. The old key keeps working for overlap_minutes (default 1440, 0 revokes it at once).
• Revocation: POST /api/api-keys/{key}/revoke. The key gets 401 within the sync interval. Revocation cannot be undone.

Plans#

Every limit is optional. A call is counted only when it passes every limit, so a call refused by the per-second rate does not use up the day's quota. Limits apply per consumer, or per key when the key has its own plan. A consumer without a plan has no limits beyond the gateway's IP rate limit. A plan that a consumer or an active key uses cannot be deleted.

Calling a protected route#

curl https://jane.eu-1.runr.example/orders/42 -H 'X-Api-Key: rk_Hk2v9QzL…'

The body is JSON: {"error": "<code>", "message": "<text>"}. Answers that let a call through cannot carry RateLimit-* headers: Traefik's forwardAuth returns the function's own answer.

When gateway-auth is not ready#

A key or JWT route never serves a call that nobody checked. It always reaches the function through its forwardAuth Middleware gw-auth-<route>. While gateway-auth cannot check calls, that Middleware asks the region's status responder instead (runr-status-responder in the Knative Serving namespace, outside the project namespace and its quota). Every call then gets:

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{"error":"auth_unavailable","message":"This API checks keys or tokens, and that check is not available right now. Try again shortly."}

A job checks gateway-auth every minute. It opens the routes when a pod is ready, closes them again when none is, retries a failed installation and moves the routes onto the metering proxy once it takes calls (GatewayAuthHealthJob). The console shows the gateway's status and message in Build & Run → API gateways, and GET /api/gateways/{id} returns them.

Usage#

GET /api/api-usage reads the hourly rows (UTC). The current hour grows until it ends. Every row and the totals carry the gateway's decisions and what the function answered to the calls let through.

{
  "from": "2026-10-01T00:00:00Z", "to": "2026-11-01T00:00:00Z", "group_by": "consumer",
  "totals": {"requests": 120345, "unauthorized": 211, "forbidden": 3, "rate_limited": 940, "quota_exceeded": 12,
             "responses": 120345, "status_2xx": 119800, "status_3xx": 0, "status_4xx": 420, "status_5xx": 118,
             "upstream_errors": 7, "errors": 125, "latency_avg_ms": 41.3, "latency_p50_ms": 27.4,
             "latency_p95_ms": 118.2, "latency_p99_ms": 410, "bytes_in": 9842211, "bytes_out": 512330871},
  "data": [{"consumer_id": "01JC…", "consumer": {"id": "01JC…", "name": "Acme Ltd", "external_id": "CUST-1042"},
            "subject": null, "requests": 120000, "unauthorized": 0, "forbidden": 3, "rate_limited": 940, "quota_exceeded": 12,
            "responses": 120000, "status_2xx": 119460, "status_3xx": 0, "status_4xx": 418, "status_5xx": 115,
            "upstream_errors": 7, "errors": 122, "latency_avg_ms": 41.2, "latency_p50_ms": 27.4,
            "latency_p95_ms": 118, "latency_p99_ms": 409.6, "bytes_in": 9800102, "bytes_out": 510991240}]
}

The gateway's decisions:

What the function answered to the calls let through, measured by the metering proxy:

The percentiles come from a latency histogram every row keeps (20 buckets with the bounds 2, 5, 10, 20, 30, 50, 75, 100, 150, 200, 300, 500, 750, 1000, 2000, 3000, 5000, 10 000 and 30 000 ms). A group — an hour, a month, a consumer, a key, a route — adds the buckets of its rows and interpolates inside the bucket a percentile falls in, so a percentile is exact to its bucket; above 30 s it reads 30 000.

Refused calls without a known consumer (no key, unknown key) have consumer_id: null. JWT callers that are not consumers are listed by subject. Public routes have no consumer and are not measured (responses: 0), nor are hours before 0.6.0. Hourly rows are kept for 400 days (apiProduct.usageRetentionDays). The console shows the same under Build & Run → API gateways → Usage: the success rate, errors, p50 · p95 · p99 and bytes of the range, and the errors and percentiles of every row (its status classes and bytes in the row's tooltip).

Usage events#

With the Billing module, usage is also recorded in the organization's billing event log and sent to its signed webhook, with the same envelope, signature, retries and GET /api/billing/events as every billing event:

Each consumer entry carries consumer.external_id, so an invoicing system can bill a month from one api.usage.monthly event per gateway. Without the Billing module the usage API is the only source.

Only through the gateway#

gateway_only: true on a route makes the project's Knative Service cluster-local, so its own address https://<slug>.<function domain> stops serving and callers cannot get around the route's keys. The gateway still reaches the project. A project with custom domains cannot be made gateway-only (the domains would get around it), and a gateway-only project cannot get a custom domain. Removing the route opens the project's own address again.

On a route to an environment it does the same to the environment's Service: its own address https://<slug>-<name>.<function domain> stops serving, production's address does not change, and the environment's custom domains are what keep it from becoming gateway-only.

Custom domain#

A gateway can be served on a domain of your own, such as api.example.com. Like a project domain, it is proven by DNS before RunR routes it:

1. PUT /api/gateways/{gateway}/custom-domain with {"domain": "api.example.com"}. The answer's custom_domain_pending names the TXT record (_runr-challenge.api.example.com = runr-verify=<token>) and the records that route the name (a CNAME to the gateway's host, or an A / AAAA record of the region's external address).
2. Create the records, then POST /api/gateways/{gateway}/custom-domain/verify. When both are found the name becomes custom_domain and the gateway is synced. Otherwise the answer is 422 and says what is missing.
3. DELETE /api/gateways/{gateway}/custom-domain stops serving it.

A name used by another gateway or project, or under a region's function domain or the console's domain, is refused. Only a verified name is ever written to custom_domain.

Developer page#

PATCH /api/gateways/{gateway} with {"developer_page": true, "description": "…"} publishes a public page at https://<console>/developers/<key> (developer_page_key in the gateway). The page shows the description, the base URLs, the routes (path, methods, authentication) and how to send a key or token. It needs no sign-in and shows no project names. There is no self sign-up in this version: the owner creates consumers and hands out keys.

"developer_page_metrics": true (console: Domain and page; runr gateway page --metrics) adds each key or JWT route's health of the last 7 days to the page (routes[].health): the share of answers without error and the latency p50, p95 and p99 — never call counts or consumers.

Permissions#

API#

Every change is in the audit log (api_consumer.*, api_key.*, api_plan.*, gateway.create, gateway.domain.*, gateway.route.*). Key secrets are never in it.

CLI and MCP#

runr gateway lists gateways and manages routes, consumers, keys, plans and usage (cli.md); runr gateway usage shows the errors and latency percentiles of every row, -o json the whole answer. The MCP server offers gateways_list, gateway_route_add (a route with its authentication, in one call), gateway_route_update, api_consumers_list, api_consumer_create, api_plans_list, api_plan_create, api_key_create, api_key_rotate, api_key_revoke (with confirm: true) and api_usage, whose rows carry the answers' fields too (mcp.md).

Region requirements and operation#

• The region's Traefik (installed by RunR) and its project namespace. Redis is optional (it gives shared counters and two pods).
• The region must reach RunR's API for the sync and the reports. The address is apiProduct.callbackUrl, or else the URL the region agent connects to (regions.md).
• Objects in the project namespace: Secret, Deployment and Service runr-gateway-auth (requests 50m CPU / 64 MiB, limits 1 CPU / 256 MiB per pod — the metering proxy streams the routes' calls through it —, non-root, read-only root filesystem), Service runr-gateway-auth-proxy (port 80 to the pods' port proxy, 8081; ready pods only), one Middleware gw-auth-<route> per key or JWT route, and for the metered routes of projects in access mode allowlist or "only through the gateway" a Middleware gw-up-<route> and the gateway's IngressRoute and Middleware gw-<id>-upstream on the web entry point.
• region:reconcile applies gateway-auth again when a release changes its image or its Deployment (annotation runr.sh/spec-revision), and rebuilds the routes of every gateway whose IngressRoute does not carry the routing revision of the release (label runr.dev/routing-revision; step gateway-routes, after gateway-auth). A region upgraded from an earlier release so gets the current routing — the Host rewrite per route, the forwardAuth Middlewares, the direct routes of allowlist and gateway-only projects, the metering proxy — without waiting for a deploy or a route change; --dry-run names the gateways it would rebuild.
• A completed or rolled back base-domain or organization-domain migration rebuilds the region's gateways at once: their default host and their routes' Host rewrites follow the new domain (regions.md).
• Helm values: apiProduct.gatewayAuthImage, callbackUrl, syncSeconds, usageRetentionDays (helm-values.md). An air-gapped region needs the image in a registry it can reach.
• When gateway-auth cannot be installed or is not ready, the key and JWT routes answer 503 auth_unavailable and the gateway shows pending or error with the reason (When gateway-auth is not ready). The status responder in the Knative Serving namespace (ghcr.io/brf-tech/runr/reqs/node:22-alpine, 10m CPU / 16 MiB) is installed for this when needed.
• runtime/ci.sh gateway-auth [--push] builds the image. runtime/ci.sh test-api-product runs the Kind end-to-end suite.

Limits of this version#

• RateLimit-* headers are sent on 429 answers only.
• No self sign-up or key requests on the developer page.
• A gateway-only project depends on the gateway reaching cluster-local Services through the region Traefik's private entry point.