How would you design a multi-tenant REST API?

Long Answer

Designing a multi-tenant REST API means every request must resolve the tenant unambiguously, every resource must be scoped to that tenant, and every limit, policy, and audit trail must be tenant aware. The strategy combines clear resource modeling, layered isolation, and operational controls that scale.

1) Tenant resolution and API surface
Choose one primary tenant locator and back it with a cryptographic claim:

• Subdomain routing: https://acme.api.example.com/v1/.... Pros: strong visual separation, easy routing and certificates, clearer caches. Cons: wildcard DNS and certificate management.
  
• Path scoping: https://api.example.com/v1/tenants/{tenant_id}/.... Pros: simpler DNS, easier local development. Cons: longer paths, more chances to forget scoping.
  

Regardless of choice, include a signed tenant identifier in the access token (for example, an OpenID Connect claim) and reject any mismatch between token and requested tenant to avoid confused deputy issues. Disallow ambiguous cross-tenant queries.

2) Resource modeling and identifiers
Keep resources tenant scoped and hierarchical where relationships are strong:

• tenants/{tenant_id}/users/{user_id}
  
• tenants/{tenant_id}/projects/{project_id}/tasks/{task_id}
  

Use stable, surrogate identifiers (for example, UUID Version 7). Provide list endpoints with cursor pagination, filtering, and sorting. Prefer additive evolution: new optional fields, new subresources, and new query parameters. For writes, require idempotency keys on unsafe methods to protect against retries.

3) Access control model
Combine role-based and attribute-based access control:

• Role-based access control defines coarse permissions (for example, Administrator, Manager, Member, Support).
  
• Attribute-based access control refines with attributes (for example, resource owner, department, region, sensitivity tag).
  

Decide at the policy layer, not the controller. Each request carries identity, roles, and attributes in the token; the policy engine evaluates rules and returns allow, deny, or filtered fields. Document permission matrices and include a 403 with a machine-readable code when denied.

4) Data isolation and safety
Isolation is a layered concern:

• Application layer: every query is scoped by the resolved tenant identifier, never by client-supplied fields alone.
  
• Database layer: enforce row-level security or separate schemas or databases per tenant depending on risk and scale. Use tenant-specific encryption keys when required.
  
• Background jobs: include tenant context in job payloads and enforce per-tenant concurrency to prevent noisy neighbors.
  

5) Rate limits and quotas per tenant
Implement limits at the edge:

• Rate limits: token bucket per tenant and optionally per user or per client application. Return 429 with Retry-After.
  
• Quotas: monthly or daily caps on billable units (for example, reports generated, storage used, messages sent). Expose usage with headers such as X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Period, and X-Quota-Remaining. Emit events when thresholds are crossed so customers and internal systems can react.
  

6) Versioning, errors, and contracts
Adopt a clear versioning strategy (for example, major version in path). Changes are backward compatible whenever possible. Use a consistent error envelope with stable codes, correlation identifiers, and user-actionable messages. Publish an OpenAPI contract and a change log; provide a sandbox.

7) Consistency, concurrency, and idempotency
Favor single-writer semantics per tenant domain aggregate where feasible. Use conditional requests (If-Match with entity tags) to prevent lost updates. Accept idempotency keys on POST and PATCH to ensure exactly-once effects under retries. For eventual consistency across subsystems, emit domain events tagged with tenant identifiers and provide a reconciliation endpoint.

8) Observability, auditing, and supportability
Emit structured logs with correlation identifiers, tenant identifiers, principal identifiers, and route names. Track latency, error rates, and saturation per tenant and per route. Maintain a complete audit trail of security-sensitive operations, including before and after summaries where allowed. Provide a support mode with break-glass approval and full audit coverage.

9) Security and privacy
Use least privilege for every service account. Support customer-managed keys if required. Minimize data in logs; redact secrets, tokens, and personal data. Enforce scopes and claims in tokens; invalidate tokens when tenants are suspended. For shared endpoints, double check that caches vary by tenant and authorization.

10) Documentation and developer experience
Deliver tenant-aware examples for both subdomain and path styles. Provide a quickstart with environment setup, a test tenant, and sample API calls that demonstrate limits and errors. Make contract tests available so client teams can verify compatibility during upgrades.

This combination produces a REST API design that is easy to consume, safe to evolve, and robust under scale, while upholding strict tenant isolation, fair usage, and strong governance.

‍

Table

‍

Common Mistakes

• Relying on only subdomains or only headers without verifying the tenant claim in the token.
  
• Allowing unscoped queries and trusting client-sent tenant identifiers inside payloads.
  
• Using shared caches that do not vary by tenant and authorization headers.
  
• Applying global rate limits that let one tenant starve others, or limits that ignore user or token.
  
• Lacking idempotency keys for unsafe methods, leading to duplicate creations under retries.
  
• Returning inconsistent error bodies that cannot be automated against.
  
• Mixing authorization checks in controllers and data access, producing gaps and drift.
  
• No audit trail for privileged actions, making incident response and compliance difficult.
  
  

Sample Answers (Junior / Mid / Senior)

Junior:
“I would expose tenant-scoped endpoints using a path like tenants/{tenant_id}/.... I would validate that the token claim matches the tenant parameter. I would add cursor pagination and idempotency keys for POST. I would enforce rate limits per tenant and return headers that show remaining usage.”

Mid:
“My multi-tenant REST API resolves tenant by subdomain or path and confirms it against a signed claim. Resources are hierarchical and use stable identifiers. Access control combines roles and attributes in a centralized policy engine. Limits use per-tenant buckets and quotas with usage headers. I use conditional requests for concurrency, structured error objects, and tenant-scoped logging and audits.”

Senior:
“I design tenant resolution at the edge with strict claim verification and defense in depth in the data layer using row security or separate schemas, plus per-tenant keys. Rate limits and quotas apply per tenant and per token with clear telemetry. Policies are role-based with attributes and are evaluated centrally. Idempotency keys and entity tags ensure safe retries and concurrency. Versioning is additive with a published OpenAPI contract and a change log.”

‍

Evaluation Criteria

A strong answer outlines REST API design choices that make multi-tenancy explicit and safe: deterministic tenant resolution, tenant-scoped resources, and defense in depth at the application and database layers. It should describe role-based and attribute-based access control, per-tenant rate limits and quotas with usage headers, idempotency keys, conditional requests, and a consistent error envelope. It should include versioning and contract governance, observability and audit trails per tenant, and a clear stance on subdomain versus path. Red flags include trusting payload tenant identifiers, global limits only, missing idempotency, cache leakage across tenants, and ad hoc authorization scattered through the code.

‍

Preparation Tips

• Prototype both subdomain and path styles; feed tenant context from the gateway and verify against token claims.
  
• Model three resources with tenant-scoped hierarchies and cursor pagination.
  
• Implement a token bucket rate limiter keyed by tenant and token; add quota counters and headers.
  
• Add idempotency keys for POST and PATCH with replay protection storage.
  
• Wire a policy engine for role-based and attribute-based access control; write at least five rules.
  
• Enforce row-level security or schema-per-tenant and prove that cross-tenant access fails.
  
• Publish an OpenAPI contract, a structured error model, and a change log.
  
• Create dashboards for tenant-scoped latency, error rates, and usage; attach audits to privileged routes.
  
  

Real-world Context

A collaboration platform moved from a header-only tenant model to subdomains plus token claims, eliminating a class of confused deputy bugs. After introducing tenant-scoped rate limits and quotas with usage headers, a single tenant’s batch importer stopped degrading others. A payments vendor enforced row-level security and per-tenant encryption keys; a simulated misrouting test could not cross boundaries. Adding idempotency keys and conditional requests removed duplicate orders during network retries. Finally, a structured error envelope and OpenAPI contract allowed downstream teams to self-serve upgrades. The multi-tenant REST API became safer to consume and easier to operate at scale.

‍

Key Takeaways

• Resolve tenant deterministically and verify it against a signed token claim.
  
• Scope resources by tenant and enforce isolation in application and data layers.
  
• Apply per-tenant rate limits and quotas with transparent usage headers.
  
• Use role-based and attribute-based access control, idempotency keys, and conditional requests.
  
• Govern with versioned contracts, structured errors, observability, and complete audit trails.
  
  

Practice Exercise

Scenario:
You are designing a multi-tenant REST API for a project management platform. Enterprise customers require strict isolation, visible quotas, and fine-grained permissions. Traffic spikes during quarter-end exports.

Tasks:

1. Choose tenant resolution (subdomain or path) and describe how you will verify the tenant claim in tokens and reject mismatches.
   
2. Define three resource groups with tenant-scoped routes and identifiers: projects, tasks, and members. Include list, create, update, delete, and a filtered search.
   
3. Specify role-based and attribute-based access control: roles, attributes, and at least five example rules. Show how the policy engine evaluates a request.
   
4. Implement idempotency for creates and updates and describe where idempotency keys are stored and how long they live. Add conditional requests with entity tags.
   
5. Design rate limits and quotas per tenant and per token, and define the response headers that expose usage. Include a plan for automated alerts when thresholds are crossed.
   
6. Describe data isolation in the database: either row-level security with tenant predicates or schema per tenant, plus per-tenant encryption keys if required.
   
7. Define the error envelope structure and a versioning strategy. Include an example 403 and 429 response.
   
8. List the tenant-scoped metrics, logs, and audit fields you will capture, and outline dashboards needed for support and reliability.
   
   

Deliverable:
A concise architecture and contract specification showing a safe, evolvable REST API design for multi-tenancy with isolation, per-tenant limits, and robust access control.