How do I set up API traffic routing by tenant or customer?

Setting up API traffic routing by tenant/customer usually means ensuring each request is identified, authorized, and routed to the correct backend, datastore, or configuration based on a tenant key.

Common patterns

1) Tenant in the request path

Example:

• api.example.com/tenant-a/orders
• api.example.com/tenant-b/orders

Pros

• Easy to debug
• Works well with gateways and caches
• Clear separation

Cons

• Tenant ID is exposed in the URL
• Can be awkward for deeply nested APIs

---

2) Tenant in a header

Example:

• X-Tenant-Id: tenant-a

Pros

• Keeps URLs clean
• Good for internal services and gateways

Cons

• Must be validated carefully
• Easier to spoof unless enforced by auth claims

---

3) Tenant from auth token / claims

Example:

• JWT contains tenant_id
• Routing uses the authenticated identity’s tenant

Pros

• Stronger security
• Less client responsibility

Cons

• Requires auth integration
• Harder for multi-tenant admin tools that access multiple tenants

---

4) Tenant by subdomain

Example:

• tenant-a.api.example.com
• tenant-b.api.example.com

Pros

• Great for customer-facing separation
• Easy DNS/TLS setup with wildcards

Cons

• More infrastructure complexity
• Usually best for B2B SaaS style setups

---

Typical architecture

At the edge / API gateway

Use an API gateway or ingress to:

1. Authenticate the request
2. Extract tenant identity
3. Apply rate limits/quotas per tenant
4. Route to the correct upstream service or cluster
5. Inject tenant context into downstream requests

Examples of tools:

• Kong
• Apigee
• NGINX / NGINX Ingress
• AWS API Gateway
• Azure API Management
• Istio / Envoy

---

Routing models

A) Shared service, shared database

All tenants use the same app and database, but every query is filtered by tenant ID.

Best for:

• Small to medium multi-tenant systems
• Simpler operations

Need:

• Strong tenant isolation in code
• Row-level security if possible

---

B) Shared service, separate database/schema per tenant

Requests are routed to the same app, but the app selects the correct schema/db based on tenant.

Best for:

• Higher isolation
• Compliance requirements

Need:

• Tenant-to-database mapping
• Connection management
• Migration orchestration

---

C) Separate service/cluster per tenant

Each tenant gets its own deployment or namespace.

Best for:

• Large enterprise customers
• Strong isolation
• Premium tiers

Need:

• Service discovery
• Tenant registry
• Operational automation

---

A practical implementation flow

1. Authenticate the request

   • Validate API key, OAuth token, or mTLS identity

2. Resolve tenant

   • From path, header, subdomain, or token claims

3. Authorize tenant access

   • Verify the caller is allowed to access that tenant

4. Look up routing metadata

   • Example: tenant-a -> cluster-1 -> db-12

5. Apply routing

   • Forward to the right backend or attach tenant context

6. Enforce tenant-specific policies

   • Rate limits
   • Quotas
   • Logging
   • Audit trails

---

Important security rules

• Never trust tenant IDs supplied by the client unless validated against auth context
• Enforce tenant isolation at multiple layers:
  • Gateway
  • Service
  • Database
• Prevent cross-tenant data leakage in caches, logs, and error messages
• Use per-tenant rate limiting to avoid noisy-neighbor issues

---

Example design

Request

GET /orders
Authorization: Bearer eyJ...
X-Tenant-Id: tenant-a

Gateway logic

• Validate JWT
• Extract tenant_id=tenant-a from token
• Compare with X-Tenant-Id
• Reject if mismatch
• Route to backend cluster for tenant-a
• Add internal header:

X-Resolved-Tenant: tenant-a

---

If you're using a gateway

Example rules

• Match on X-Tenant-Id
• Or derive tenant from JWT claim
• Route to upstream based on mapping table
• Add rate limit key = tenant ID

Example pseudo-logic

if tenant_id in allowed_tenants(user):
    route_to = tenant_routing_table[tenant_id]
else:
    deny_request()

---

Best practices checklist

• Choose one canonical tenant identifier
• Derive tenant from trusted identity whenever possible
• Centralize routing metadata in a tenant registry
• Add per-tenant rate limits and quotas
• Log tenant ID in every request trace
• Test for cross-tenant access violations
• Plan for tenant onboarding/offboarding automation

---

If you want, I can also give you:

1. a reference architecture diagram,
2. NGINX/Kong/API Gateway configuration examples, or
3. a code sample in Node/Python/Java for tenant-based routing.