Redis Keyspace Reference

All Gatez services share a single Redis instance (gw-redis:6379). Keys are namespaced by function and always include tenant_id where applicable to enforce multi-tenant isolation.

Key Pattern Reference

Key Pattern	Type	Service	TTL	Description
rl:{tenant_id}:{route_id}:{window}	Sorted Set	L1 (APISIX tenant-rate-limit)	window + 1 seconds	Sliding window rate limit bucket. Members are {timestamp}:{random}, scored by timestamp.
rl:config:{tenant_id}	String	L1 (APISIX tenant-rate-limit)	None	Per-tenant rate limit override. Value is the max request count per window.
rl:{tenant_id}:config:rate	String	Control Plane API	None	Tenant rate limit configuration. Set during tenant provisioning based on plan.
rl:global:config:rate	String	Control Plane API	None	Global default rate limit. Falls back to 5000 if unset.
{tenant_id}:budget:tokens	String (integer)	AI Gateway / Control Plane API	None	Remaining token budget for a tenant. Decremented after each LLM response.
{tenant_id}:cache:ai:{model}:{hash}	String	AI Gateway (cache.rs)	Configurable (cache_ttl_secs)	Exact-match LLM response cache. Key includes SHA-256 hash of normalized tenant_id:model:prompt.
session:{session_id}	String (JSON)	Agent Gateway (sessions.rs)	Session TTL (default from config)	Agent session state. Contains tool allowlist/denylist, token budget, tool call count, and metadata.
session:tenant:{tenant_id}:sessions	Set	Agent Gateway (sessions.rs)	None	Index of session IDs belonging to a tenant. Used for listing sessions.
policy:tenant:{tenant_id}	String (JSON)	Agent Gateway (security.rs)	None	Tenant security policy. Controls tool access, HITL gates, max sessions, blast radius limits.
hitl:{id}	String (JSON)	Agent Gateway (security.rs)	3600s (1 hour)	Human-in-the-loop approval or MCP elicitation request. Contains tool name, arguments, status, and optional elicitation schema/response.
hitl:pending:{tenant_id}	Set	Agent Gateway (security.rs)	None	Index of pending HITL request IDs for a tenant. Entries removed on approval/denial.
a2a:agent:{agent_id}	String (JSON)	Agent Gateway (routes.rs)	None	A2A agent card. Contains agent ID, tenant ID, capabilities, and registration metadata.
a2a:agents:{tenant_id}	Set	Agent Gateway (routes.rs)	None	Index of A2A agent IDs registered by a tenant.
tenant:{tenant_id}:meta	Hash	Control Plane API (tenants.rs)	None	Tenant metadata. Fields: name, plan, status, rate_limit_max, token_budget, created_at.
tenant:{tenant_id}:keys	Set	Control Plane API (keys.rs)	None	Set of API key IDs belonging to a tenant.
tenant:{tenant_id}:branding	String (JSON)	Control Plane API (branding.rs)	None	Tenant portal branding. Contains logo_base64, portal_title, primary_color.
tenants:all	Set	Control Plane API (tenants.rs)	None	Global set of all tenant IDs. Used for listing/iterating tenants.
key_request:{id}	String (JSON)	Control Plane API (keys.rs)	None	Pending API key request. Contains requester email, tenant, routes, reason. Deleted on approval/denial.
key_requests:pending	Set	Control Plane API (keys.rs)	None	Set of pending key request IDs.
api_key:{key_id}	String (JSON)	Control Plane API (keys.rs)	None	API key metadata. Contains prefix (masked), tenant, routes, status, creation date.
notifications:{tenant_id}	List	Control Plane API (notifications.rs)	None	Notification list for a tenant. Capped at 100 entries via LTRIM. Newest first (LPUSH).
notif_prefs:{tenant_id}	String (JSON)	Control Plane API (notifications.rs)	None	Notification preferences. Contains webhook URL, Slack URL, email, enabled notification types.
platform:settings	String (JSON)	Control Plane API (settings.rs)	None	Global platform settings. Contains platform name, default rate limit, default token budget, data retention config, notification config.

Key Design Principles

Tenant Isolation

Every key that stores tenant-specific data includes the tenant_id in its key path. This ensures:

• No cross-tenant data leakage in cache lookups
• Independent rate limit buckets per tenant
• Separate token budgets per tenant

WARNING

Never use a Redis key pattern that could allow one tenant's data to be read or modified by another. Every tenant-scoped operation must include tenant_id in the key.

Connection Pooling

• L1 (APISIX Lua): Uses resty.redis with set_keepalive(10000, pool_size). Default pool size: 100.
• L2/L3 (Rust): Uses redis::aio::ConnectionManager which maintains a single multiplexed connection.
• Control Plane: Uses redis::aio::ConnectionManager via the shared Clients struct.

Fail-Open Policy

The L1 tenant-rate-limit plugin fails open if Redis is unreachable. Requests are allowed through rather than blocked, preventing Redis outages from causing a full gateway outage.

Query Examples

Check a tenant's rate limit configuration

# Connect to Redis
redis-cli -h localhost -p 6380

# Get tenant rate limit override
GET rl:config:tenant-alpha

# Get tenant rate limit from control plane config
GET rl:tenant-alpha:config:rate

# Get global default
GET rl:global:config:rate

Inspect a tenant's token budget

# Current remaining budget
GET tenant-alpha:budget:tokens

List all sessions for a tenant

# Get session IDs
SMEMBERS session:tenant:tenant-alpha:sessions

# Get a specific session
GET session:{session-id}

View pending HITL approvals

# List pending approval IDs for a tenant
SMEMBERS hitl:pending:tenant-alpha

# Get approval details
GET hitl:{approval-id}

List all registered tenants

SMEMBERS tenants:all
HGETALL tenant:tenant-alpha:meta