Skip to content

CONCEPT Cited by 1 source

Session-token-embedded routing context

Session-token-embedded routing context is the design pattern in which a session token (the bearer credential proving a logged- in user) also carries tenant/shard routing information that the backend parses on every request to decide where to route the query and what access-control context to apply.

The canonical wiki instance is Slack's 2013 "workspace tokens" (Source: sources/2024-08-26-slack-unified-grid-how-we-re-architected-slack-for-our-largest-customers): "Slack clients authenticated their API requests using session tokens containing the user ID and workspace ID; the backend then parsed the workspace ID and used it to associate each API request with a workspace, route queries to that workspace's database shard and perform access control."

Why it's convenient

  • O(1) routing at request-parse time. No extra DB lookup to decide which shard to talk to; the routing info is in the already-authenticated envelope.
  • Access-control scope is self-evident. The session's tenant scope is the authorisation scope — a request can only affect data within its token's tenant.
  • Simple sharding mental model. "This session is for workspace X" maps directly to "queries go to workspace X's shard."

The structural coupling

The hidden cost: the session's granularity determines how much data you can expose in a single authenticated request. Any view that spans multiple tenants — an activity feed across tenants, a DM list spanning tenants, a global search — either needs to:

  • Make multiple authenticated requests across multiple session tokens (expensive — every tenant switch means a new session).
  • Introduce aggregation APIs that fan-out to per-tenant shards and merge (expensive, and a scatter-gather shape).
  • Or break the tenant scoping of session tokens — re-architect the routing axis.

When the product accumulates enough multi-tenant views that the first two options become pathological, option 3 is the only way out, and it is what Slack's workspace-scoped-to-org-wide migration canonicalises.

Distinction from other token shapes

  • concepts/idempotency-token — tokens that make replay of a request safe. Orthogonal concern; idempotency tokens don't carry routing.
  • concepts/discharge-token — Macaroons-style tokens that carry delegated/attenuated authority. Not routing context; capability restriction.
  • concepts/authorization-vs-authentication-token — the general authn-vs-authz token distinction. Session-token- embedded routing context is a third axis: tenant-context.
  • JWT with tenant claim — a common modern shape. Same structural coupling as Slack's workspace tokens: every request routes by the token's tenant claim, and the session can only see data in that tenant.

Generalisation — any tenant-carrying session envelope

The pattern appears whenever a multi-tenant system chooses to embed the tenant ID in the session credential rather than pass the tenant ID as a per-request parameter (or resolve it from the target resource ID). Examples likely to have this shape:

  • GitHub before Enterprise accounts — session scoped to a personal user; per-org access resolved via membership lookup per-request (the other shape — no tenant in the session token).
  • Stripe test/live mode — the API key embeds the mode and the account; every request routes accordingly.
  • AWS STS temporary credentials — scoped to a specific assume-role context.

When the session-token-embedded routing context is too narrow for the product's new usage pattern, the migration is to either (a) broaden the token's scope (Slack's choice — tokens span the org), (b) decouple routing from the session (route by resource ID instead), or (c) layer a new session-envelope on top (e.g. GitHub's enterprise account session spanning orgs).

Seen in

Last updated · 470 distilled / 1,213 read