Henry Hoang
Lesson 3 of 5 · 6 min read

How Multi-Tenancy Works in a Serverless SaaS on AWS

How the template keeps customers apart in shared tables: choosing a model, the login token and tenant keys.

In saas-backend-v2, all customers share the same tables and functions, and two rules keep them apart. The login token decides which workspaces a user may act in, and each workspace's data is stored under its own id.

This post explains when you need multi-tenancy, how to choose a model, how to implement it, and where this approach is still weak. If you're new here, start with what's in the template.

Do you need it?

You need multi-tenancy when one product serves many customer organizations and each must see only its own data. An internal tool for one company doesn't need it, and neither does an app where each person only sees their own data. That's my rule of thumb, not AWS's.

In this template, a tenant is a workspace. One user can belong to several, and each browser tab can work in a different one.

Choose a model

AWS describes three models, and you can choose differently for each service.

ModelWhat it meansChoose it whenWhat it costs you
SiloEach tenant gets dedicated resourcesStrict compliance, noisy-neighbor worries or per-tenant cost trackingHigher cost, heavier onboarding and decentralized management
PoolTenants share resourcesYou want economies of scale and simple operationsIsolation is harder and needs extra care
BridgeSome services silo, others poolServices differ in data rules or loadTwo models to operate (my reading, not AWS's)

This template pools everything, which suits small and mid-sized customers. AWS's DynamoDB guidance describes the same trade: easier management, in exchange for more concern about noisy neighbors and security.

Logging in is not isolation

This is the idea to hold on to. AWS is explicit that an authenticated, authorized user could still reach another tenant's data unless every access is scoped to the current tenant. A valid token proves who someone is, not what they may touch.

So every request here goes through the same decision before any data is read.

At sign-in, a Cognito trigger lists the user's workspaces in the ID token. On every request, API Gateway checks the token, get_current_user checks the workspace and role, and every key starts with TENANT#

Implement it in five steps

1. Put the tenants in the token

A pre token generation trigger runs at every login and refresh. It adds a workspaces claim listing each workspace with the user's role and the plan, so other modules never have to ask the accounts module.

# modules/accounts/src/accounts/service.py
workspaces = {tenant.tenant_id: {"role": member.role, "plan": tenant.plan}
              for tenant, member in self.accounts.workspaces_of(user_id) if tenant.active}
return {WORKSPACES_CLAIM: json.dumps(workspaces, separators=(",", ":"))} if workspaces else {}

2. Verify the token before your code runs

A JWT authorizer on the HTTP API checks the signature, issuer, audience and expiry, then passes the claims to Lambda. One route has no JWT check: the Stripe webhook, which has no user and verifies Stripe's signature instead.

3. Resolve the tenant in one function

The request names a workspace, and the token decides whether it may. Every module API route gets its caller from get_current_user, so this logic exists in one place.

# layers/shared/layer/shared/auth.py
if claims.get("token_use") != "id":
    raise Unauthorized("Send the ID token in the Authorization header")
workspaces = workspaces_in(claims)
workspace = workspaces.get(tenant_id) if tenant_id else None
if tenant_id and not workspace:
    raise Unauthorized("Your token doesn't list this workspace; refresh it and try again")

The first check matters because the authorizer can't tell token types apart, and only ID tokens carry the workspaces claim. AWS's authorizer page notes that there is no standard way to distinguish them.

4. Start every tenant item's key with the tenant

A query on a tenant's key can't reach another tenant's partition. HTTP request schemas never contain tenant_id, so a client can't supply a different one in the body. Lookups and system records, such as USER# and OUTBOX#, use other keys.

# modules/orders/src/orders/repository.py
def _pk(tenant_id: str) -> str:
    return f"TENANT#{tenant_id}"

item = {"pk": _pk(order.tenant_id), "sk": f"ORDER#{order.order_id}", **order.model_dump(mode="json")}

5. Enforce limits in the database

A plan limit checked by reading first can be beaten by two requests at the same moment. DynamoDB transactions can check a condition and write atomically, so the check and the write can't be separated.

# modules/orders/src/orders/repository.py
counter["ConditionExpression"] = "attribute_not_exists(order_count) OR order_count < :max"

The catch: tokens go out of date

A token is a snapshot from when it was issued. ID tokens here last 15 minutes, so for any change, ask when it takes effect.

What changedWhere it's enforcedWhen it takes effect
Role or membership, for the accounts module's own actionsAccounts re-reads its tableAt once. A role change or removal by someone else also revokes refresh tokens
Role, in other modulesThe tokenWithin 15 minutes
Workspace suspended or being deletedAccounts' own record, and a status copy in orders, billing and the assistantSeconds, as the event arrives
PlanThe tokenAt the next token refresh
Joined a new workspaceThe token401 until the client refreshes

The third row was a real gap. A suspended workspace stayed in members' tokens for up to 15 minutes, so a token issued before the suspension could still add an order. Now each module keeps its own copy of the workspace's status, updated by events, and refuses changes at once.

Prove it with a test

Isolation is only worth claiming if a test fails when it breaks. The orders module tests it directly:

# modules/orders/tests/test_api.py
def test_tenants_cannot_see_each_others_orders(ctx, alice):
    _, order = ctx.api("POST", "/orders", alice, ORDER)
    zoe = claims("zoe", "t2", "owner")
    assert ctx.api("GET", f"/orders/{order['order_id']}", zoe)[0] == 404
    assert ctx.api("GET", "/orders", zoe)[1]["items"] == []

The smoke test also checks isolation with real users against a deployed stack.

Where this is still weak

Isolation lives only in application code. AWS shows IAM leading-key conditions that limit a request's credentials to one tenant's items, and this template doesn't use them. A bug in a key could cross tenants, and nothing below the code would stop it. Add them if your customers need that assurance.

One user pool is a trade-off. I use one because a person can join several workspaces with one login. A pool per tenant gives the most isolation, but each user signs up separately for each tenant and the effort is high. Either way, within one account, Cognito's quotas are shared by all tenants.

There's no per-tenant rate limit. The API's throttle of 50 requests a second covers everyone, so one busy tenant can affect the others.

Next, build your first module on top of these rules.

On this page