The API was protected. Every request required authentication. Every controller filtered by tenant_id. The dashboard had passed its security review.

The leak happened later—inside a background worker.

This is the uncomfortable part of multi-tenant SaaS security: a request can be safe while the work it creates is not. Once a task leaves the request-response cycle and enters a queue, the assumptions that protected it often disappear with the HTTP context.

The fix is not another scattered WHERE tenant_id = ? condition. Tenant identity has to become part of the job’s contract, database session, idempotency model, observability, and test strategy.

Let’s build that boundary deliberately.

TL;DR

A safe multi-tenant background job should:

Carry a server-derived tenant identifier in its payload. Re-authorize the tenant and operation when the job runs. Use tenant-scoped repositories or data-access objects. Enforce isolation again in the database, preferably with row-level security where appropriate. Include tenant identity in idempotency keys, traces, metrics, and dead-letter records. Be tested with hostile cross-tenant cases, not only happy paths.

Why background jobs escape the tenant boundary

In a web request, tenant context is usually available from one of four places:

• A verified token claim

• The authenticated user’s membership

• The requested hostname or subdomain

• A trusted server-side lookup

Middleware resolves that context, attaches it to the request, and downstream code consumes it. The boundary feels solid because every layer is participating.

A queue changes the shape of the system.

The worker may run seconds or hours later. It may run in another process, region, or cloud account. There is no request object, no browser session, and sometimes no original user. Retries can outlive membership changes. Scheduled jobs may be created once and execute for months.

If tenant context was ambient state, it is gone.

That is how seemingly harmless code turns dangerous:

// Unsafe: the worker receives only a record ID.
await queue.add("send-invoice", {
  invoiceId: invoice.id
});

worker.process("send-invoice", async (job) => {
  const invoice = await db.invoice.findUnique({
    where: { id: job.data.invoiceId }
  });

  await emailInvoice(invoice);
});

The code assumes invoice IDs are globally unguessable and that whoever queued the job was authorized. It also assumes the record will still belong to the same tenant when the worker executes.

Those are application assumptions—not security boundaries.

1. Treat tenant context as data, not atmosphere

The first design change is simple: make tenant identity explicit in the job schema.

type TenantJob<TPayload> = {
  tenantId: string;
  actorId: string | null;
  authorizationVersion: number;
  kind: string;
  idempotencyKey: string;
  requestedAt: string;
  payload: TPayload;
};

type SendInvoicePayload = {
  invoiceId: string;
};

The tenantId must come from trusted server-side context. Never accept it directly from an unverified request body because “the worker will check it later.”

The actorId answers “who initiated this?” and can be null for system jobs. authorizationVersion is optional, but it is useful when permissions or policies can change while a job waits in the queue.

Most importantly, the payload is now self-describing. An engineer inspecting a dead-letter record can tell which tenant boundary the job belongs to without reconstructing an old request.

2. Re-authorize at execution time

Authorization at enqueue time is necessary, but it is not always sufficient.

Suppose an employee requests a large export, then loses access before the worker starts. Should the export still run? There is no universal answer. A billing receipt and a customer-data export have different risk profiles.

Define the policy per operation:

Snapshot authorization: permission at enqueue time is enough. Live authorization: permission must still exist when the job executes. System authorization: the operation belongs to an internal scheduler, not an end user. Dual authorization: validate both the original request and current policy.

For sensitive exports, deletions, payments, or administrative changes, live authorization is usually the safer default.

worker.process("export-customer-data", async (job) => {
  const data = job.data as TenantJob<{ exportId: string }>;

  const tenant = await tenants.requireActive(data.tenantId);

  if (!data.actorId) {
    throw new Error("This job requires an initiating actor");
  }

  await authorization.requireCurrentPermission({
    tenantId: tenant.id,
    actorId: data.actorId,
    permission: "customer_data.export"
  });

  await runExport(tenant, data.payload.exportId);
});

This is not about distrusting the queue. It is about acknowledging time. The system that authorized a task and the system that executes it may observe different realities.

3. Make cross-tenant queries difficult to express

A shared database client is convenient. It is also an easy place to forget tenant scoping.

Instead of passing tenant Id into selected queries, construct a tenant-scoped data-access layer once and make the unsafe path awkward.

class TenantInvoiceRepository {
  constructor(
    private readonly db: Database,
    private readonly tenantId: string
  ) {}

  async findById(invoiceId: string) {
    return this.db.invoice.findFirst({
      where: {
        id: invoiceId,
        tenantId: this.tenantId
      }
    });
  }

  async markSent(invoiceId: string) {
    return this.db.invoice.updateMany({
      where: {
        id: invoiceId,
        tenantId: this.tenantId
      },
      data: {
        status: "sent"
      }
    });
  }
}

Notice the use of update Many rather than an update operation that identifies a row only by its globally unique ID. The tenant predicate remains part of the write.

A useful code-review question is:

“Can this function access a different tenant if a caller passes the wrong record ID?”

If the answer is yes, the function is operating below the boundary and needs an additional control.

4. Let the database enforce the rule too

Application checks are valuable, but they share one weakness: every future query has to remember them.

PostgreSQL row-level security (RLS) can add a second boundary. The worker sets the tenant for the current transaction, and policies restrict which rows that session can read or write.

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;

CREATE POLICY invoice_tenant_isolation
ON invoices
USING (
  tenant_id = current_setting('app.tenant_id', true)::uuid
)
WITH CHECK (
  tenant_id = current_setting('app.tenant_id', true)::uuid
);

Then establish the tenant inside the transaction:

await db.transaction(async (tx) => {
  await tx.query(
    "select set_config('app.tenant_id', $1, true)",
    [job.data.tenantId]
  );

  const repository = new TenantInvoiceRepository(
    tx,
    job.data.tenantId
  );

  await repository.markSent(job.data.payload.invoiceId);
});

The true flag makes the setting local to the transaction. That matters when connections return to a pool; tenant context must not leak into the next borrower’s session.

RLS is not a magic shield. Table owners normally bypass row security unless FORCE ROW LEVEL SECURITY is enabled, and roles with BYPASSRLS still bypass it. The worker should connect with a dedicated, least-privileged role—not the migration owner or a superuser.

Also decide what happens when app.tenant_id is missing. A fail-closed policy should return no rows or raise an error, not quietly broaden access.

5. Put the tenant inside the idempotency key

Background workers retry. Networks fail after a write but before an acknowledgement. A job can be delivered more than once.

An idempotency key prevents duplicate effects, but in a multi-tenant system its namespace must include the tenant.

const idempotencyKey = [
  tenantId,
  "send-invoice",
  invoiceId,
  invoiceVersion
].join(":");

Without tenant identity, two customers can collide if business identifiers are unique only within a tenant. The same principle applies to cache keys, distributed locks, object-storage paths, webhook deduplication, and rate-limit buckets.

A compact rule helps:

If a resource is tenant-scoped, every operational namespace around it must be tenant-scoped too.

6. Preserve context through retries and dead-letter queues

The first attempt is rarely the dangerous one. The danger appears when the job is retried by different code, replayed manually, or moved to a dead-letter queue.

Preserve the original tenantId, actorId, authorization mode, requestedAt, schemaVersion, and idempotencyKey across every transition. Do not rebuild them from partial payloads.

When an operator replays a failed job, the same authorization and tenant-validation path should run again. A replay button must not become an administrative bypass.

Version the job contract as well:

type JobEnvelope<T> = {
  schemaVersion: 2;
  tenantId: string;
  actorId: string | null;
  authorizationMode: "snapshot" | "live" | "system";
  idempotencyKey: string;
  traceId: string;
  payload: T;
};

Schema versions make migrations explicit. They also prevent an old worker from silently interpreting a new payload with the wrong assumptions.

7. Make tenant context observable—carefully

When a job fails, the first operational question is often “which customer did this affect?”

Reliable tenant isolation also depends on disciplined monitoring and observability, because missing or changing tenant context should be detected before it becomes a customer-facing incident. Add a stable tenant identifier to traces, structured logs, metrics, and audit records—then add guardrails:

• Use an internal opaque ID rather than a customer name.

• Do not put secrets, email addresses, or payload data into metric labels.

• Control who can query cross-tenant logs.

• Avoid high-cardinality metrics when a trace or log field is more appropriate.

• Alert when a job’s tenant context is missing or changes unexpectedly.

A trace should make the boundary visible:

span.setAttributes({
  "saas.tenant_id": tenantId,
  "job.kind": job.kind,
  "job.schema_version": job.schemaVersion
});

The purpose is not to create a new data leak in the observability platform. It is to make tenant flow auditable without exposing customer content.

8. Test the boundary with adversarial cases

A happy-path test proves that Tenant A can process Tenant A’s invoice. That is useful, but it does not prove isolation.

Add tests that intentionally cross the boundary:

• Queue a Tenant A job with a Tenant B invoice ID.

• Change the actor’s membership before execution.

• Replay a dead-letter job after the tenant is suspended.

• Run two tenants’ jobs concurrently on the same connection pool.

• Omit tenant context and confirm the database fails closed.

• Try a cache key or lock name that would collide across tenants.

• Verify that logs contain the opaque tenant ID but no customer data.

• Use a worker role that does not own the tables and has no BYPASSRLS privilege.

One of the most effective tests is a small matrix:

for (const jobTenant of [tenantA, tenantB]) {
  for (const recordTenant of [tenantA, tenantB]) {
    const result = await runJob({
      jobTenantId: jobTenant.id,
      invoiceId: invoices[recordTenant.id].id
    });

    expect(result.allowed).toBe(
      jobTenant.id === recordTenant.id
    );
  }
}

This catches the exact class of bug that ordinary unit tests tend to miss.

A practical architecture for tenant-safe workers

A robust flow looks like this:

The API authenticates the caller and resolves tenant membership. The API authorizes the requested operation. The producer creates a versioned job envelope with server-derived tenant context. The queue stores and transports the envelope without rewriting it. The worker validates the tenant and applies the operation’s authorization policy. A tenant-scoped repository limits application-level queries. The database enforces row access for the active tenant. Idempotency, storage, locks, and caches use tenant-scoped namespaces. Traces and audit logs record an opaque tenant identifier. Retries and replays return through the same validation path.

No single layer is perfect. The strength comes from independent controls failing in different ways.

The review checklist

Before shipping a multi-tenant worker, ask:

• Where does tenantId come from, and can a client influence it?

• Does the job carry enough context to be understood outside the original request?

• Is authorization checked at the correct time for this operation?

• Can repository methods access a record from another tenant?

• Does the database enforce isolation if an application query is wrong?

• Does the worker use a least-privileged, non-owner database role?

• Are idempotency keys, cache keys, locks, and storage paths tenant-scoped?

• Do retries, scheduled runs, and manual replays preserve the same controls?

• Can operators investigate failures without seeing customer data?

• Do tests prove that cross-tenant combinations fail?

If any answer is vague, the boundary is probably living in convention rather than architecture.

The real goal: make the safe path the easy path

Multi-tenancy is often introduced as a data-model choice: add tenant_id and filter every query.

In production, it is an execution-context problem.

Tenant identity has to survive every boundary the workload crosses—HTTP, queue, process, transaction, retry, cache, object store, and observability pipeline. When that identity is explicit and enforced by more than one layer, background work becomes easier to reason about and much harder to misuse.

The best security design is not the one that asks every engineer to remember one more rule. It is the one that makes an unsafe operation difficult to express.

If you are reviewing a live SaaS platform or modernizing a system where tenant boundaries have grown organically, the engineering team at Pinnacloid works on secure, scalable software and cloud systems.

About the author

Syed Ebad Hussain is CTO at Pinnacloid. He writes about the engineering decisions behind reliable SaaS, cloud, data, and AI systems.

Written by Syed Ebad Hussain, CTO at Pinnacloid, and published by Syed ShahNawaz with the author’s permission.