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.
gatez:agent-registry	Hash	Control Plane API (sts.rs)	None	Agent principal registry (feature-flagged: GATEZ_AGENT_IDENTITY=on). Field = agent_id, value = JSON AgentRegistration.
gatez:deleg:{agent_id}	Set	Control Plane API (sts.rs)	None	Delegation policy projection for agent identity (feature-flagged). Set of allowed audience agent IDs this agent may delegate to. Projected from Agent Registry on registration.
sts:jti:{jti}	String	Agent Gateway (sts_verify.rs)	Token TTL (120s)	Replay denylist for STS hop tokens (feature-flagged). Value = "1". L3 checks SET NX to reject replayed tokens.

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