Skip to article
Databases Data platform

Session token

A session token is the Azure Cosmos DB value returned by requests and used by clients to preserve session consistency. The SDK normally manages it automatically, but applications can pass it between requests or services when they must continue a specific read-your-writes session.

Source: Microsoft Learn - Manage consistency levels in Azure Cosmos DB Reviewed 2026-05-24

Exam trap
Treating a session token as an Azure resource that can be managed directly with CLI or ARM.
Production check
Confirm the account default consistency is Session or that the client explicitly requests session consistency.
Practice this topic Microsoft Learn
Article details and learning context
Aliases
Session token, session-token, session token, Session-token
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-24
Review level
template-specs-five-use-cases
Article depth
template-specs-five-use-cases-three-case-studies
Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

A session token is Cosmos DB’s way of remembering how far a client session has progressed for a partition. After a write, the SDK receives token information and sends it on later reads so the user does not read older data than their session has already seen. Most teams never handle it manually because the SDK tracks it. It becomes important when an application crosses service boundaries, recreates clients, or needs to resume the same session from another component.

Why it matters

Session tokens matter because session consistency only works as users expect when token state is preserved correctly. A web API can write an item, then another stateless service instance can immediately read stale data if the relevant token is lost. That creates bugs that look random: duplicate orders, missing status changes, reopened workflow steps, or dashboards that disagree with user actions. The token also teaches an important architectural lesson: consistency is not only a database setting; it is a contract between Cosmos DB and the client path. Teams that understand tokens can debug stale reads precisely instead of overreacting with stronger consistency, excessive retries, or expensive compensating queries.

Technical context

Technically, session tokens live in the Cosmos DB data plane and are tied to session consistency, partitions, request headers, SDK client behavior, and item operations. They are not Azure resources and they are not managed through ARM. CLI helps inspect the surrounding account, database, container, throughput, and region configuration, but the token itself is observed in SDK responses and diagnostics. Tokens are partition-bound, which means correct use also depends on partition key handling. They are a client-side consistency mechanism that supports read-your-writes behavior.

Exam context

What to know

operator-ready Azure glossary term with practical use cases, CLI context, and structured case studies

Compare with

Cosmos DB account Cosmos DB database

Where it is used

Where you see it

  1. In Cosmos DB SDK response headers or diagnostics, session-token values appear after writes and are reused by the client for later session-consistent reads within the same partition.
  2. In application logs, safe redacted diagnostics may show session-token presence, request charge, partition key, consistency level, and retry count for write-read workflows during incidents and audits.
  3. In architecture reviews, session token flow appears in diagrams where API gateways, workers, or mobile clients must preserve read-your-writes behavior across service boundaries in production.

Common situations

  • Preserve read-your-writes behavior when a write and follow-up read cross API gateways, workers, or app instances.
  • Troubleshoot stale read bugs by proving whether SDK-managed session tokens are retained, lost, or incorrectly shared.
  • Resume a user workflow from another service component without forcing the entire Cosmos DB account to strong consistency.
  • Validate mobile or reconnecting clients that must read recent writes after network interruptions or service failover.
  • Reduce duplicate retries and compensating queries by fixing token propagation instead of raising RU throughput.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Travel booking API fixes disappearing itinerary updates Scenario, objectives, solution, measured impact, and takeaway.
Scenario

A travel booking platform stored itinerary changes in Cosmos DB. Customers who changed a flight and immediately viewed the itinerary sometimes saw the old segment, leading them to submit duplicate changes.

Goals
  • Preserve read-your-writes behavior across API gateway and itinerary service calls.
  • Reduce duplicate change requests without increasing global consistency.
  • Keep p95 itinerary refresh latency below 200 milliseconds.
  • Give support engineers correlation evidence for stale-read reports.
Approach using Session token

Developers found that the booking API wrote the itinerary item, then redirected the client to a read endpoint served by a different app instance. The SDK session token from the write response was not carried into that read path. The team kept the account on Session consistency, added a redacted session-context field to the internal workflow, and reused Cosmos clients instead of constructing them per request. Azure CLI exports confirmed the account consistency policy, regions, container partition key, and throughput before testing. Synthetic transactions changed itineraries, followed redirects, and verified the updated segment through the same public API route. Logs recorded request charge, partition key, correlation ID, and token presence without exposing the raw token.

Potential outcomes
  • Duplicate itinerary change requests decreased by 72 percent in six weeks.
  • Itinerary refresh p95 stayed at 163 milliseconds, avoiding a move to stronger consistency.
  • Support escalations for old itinerary views fell from 95 per week to 18.
  • Synthetic write-read tests passed 99.98 percent of runs after the token propagation fix.
What to learn

Session tokens solve real user confusion when teams preserve them across the exact service path that follows a write.

Scenario 02 Field maintenance app survives offline reconnects Scenario, objectives, solution, measured impact, and takeaway.
Scenario

An energy services company used a mobile maintenance app for technicians inspecting wind turbines. After reconnecting from offline mode, technicians sometimes could not see the work note they had just uploaded.

Goals
  • Make uploaded work notes visible immediately after mobile reconnection.
  • Avoid broad query retries that drained device battery and consumed extra RUs.
  • Keep partition-aware reads aligned with turbine and work-order identifiers.
  • Provide diagnostics that mobile and cloud teams could share.
Approach using Session token

The mobile team reviewed Cosmos DB SDK diagnostics and found the app uploaded notes through one service but refreshed the work order through another endpoint after reconnecting. The session token from the write response was not included in the refresh call, and some reads targeted a broader partition range. Engineers adjusted the reconnect workflow to retain session context for the affected work order, then read the item using the correct partition key before loading summary data. Operators used CLI to confirm the account default consistency and container partition key path in staging and production. A test harness simulated offline uploads, network loss, reconnect, and immediate readback from field devices with poor connectivity.

Potential outcomes
  • Immediate note visibility improved from 91 percent to 99.9 percent in reconnect tests.
  • Average post-reconnect RU consumption per work order dropped by 38 percent.
  • Technician duplicate note submissions fell by 57 percent during the next maintenance cycle.
  • Battery drain complaints tied to repeated refresh attempts declined noticeably in field feedback.
What to learn

For mobile workflows, session-token continuity can be the difference between a reliable reconnect and a technician repeating work.

Scenario 03 Subscription billing service removes costly consistency workaround Scenario, objectives, solution, measured impact, and takeaway.
Scenario

A subscription billing team saw stale invoice status reads after payment writes. To mask the issue, the service performed repeated broad queries until the new status appeared, inflating RU usage near billing close.

Goals
  • Eliminate broad polling queries after invoice status updates.
  • Keep invoice status read-your-writes behavior across billing microservices.
  • Reduce RU spikes without changing the account to strong consistency.
  • Create a repeatable diagnostic package for monthly close incidents.
Approach using Session token

Architecture review showed that the payment service wrote invoice status with Session consistency, but the invoice viewer used a separate service instance and ignored the session token. Developers added token-aware workflow metadata for the invoice partition and changed the viewer to perform a targeted read before loading aggregate billing lists. Operators captured CLI evidence for consistencyPolicy, container throughput, and regional configuration, then compared RU metrics before and after the change. The old polling loop was removed behind a feature flag. During the next close cycle, diagnostics showed single targeted reads with low retry counts instead of repeated cross-partition queries. Support dashboards displayed correlation IDs so agents could verify the write and read path quickly.

Potential outcomes
  • RU consumption during billing close dropped by 46 percent.
  • Invoice status refresh p95 improved from 780 milliseconds to 210 milliseconds.
  • Broad polling queries after payment writes were reduced from 12 million per month to under 300,000.
  • No account-level consistency change was required, preserving the existing availability and latency profile.
What to learn

Understanding session tokens can remove expensive workarounds that hide stale-read bugs instead of fixing their cause.

Azure CLI

I use Azure CLI around session-token investigations even though CLI does not retrieve live SDK tokens. The reason is practical: stale-read incidents need environmental proof before developers chase code paths. CLI shows the account consistency level, regions, containers, throughput settings, and sometimes keys or diagnostic scopes that frame the investigation. It also lets me compare production and staging quickly. When I pair that output with SDK diagnostics that include session-token behavior, the team can separate database configuration from client misuse. That saves time and prevents risky changes to consistency policy when the real issue is token propagation. It also proves whether the account-level consistency policy supports the token behavior developers expect.

Useful for

  • Confirm the Cosmos DB account default consistency before investigating whether session tokens should be in play.
  • List databases and containers to identify the exact partitioned resource involved in a stale-read incident.
  • Inspect account regions and failover settings before testing token-sensitive behavior across regions.
  • Export throughput settings and metrics to see whether retry storms are increasing RU consumption.
  • Gather environment evidence for developers who will inspect SDK diagnostics and token propagation.

Before you run a command

  • Confirm tenant, subscription, resource group, account name, database, container, and API before gathering evidence.
  • Remember Azure CLI cannot display live SDK session tokens; it validates account and container context around them.
  • Coordinate with developers before enabling diagnostics that could log headers or sensitive request metadata.
  • Use least-privilege access and avoid listing keys unless the investigation truly requires security-impacting information.
  • Know the partition key and user workflow because session tokens are meaningful only with the right item and partition context.

What the output tells you

  • The consistency policy confirms whether Session is the account default and whether token behavior should be expected.
  • Container output identifies partition key paths, indexing, and resource scope for the workflow under investigation.
  • Region and failover output shows whether cross-region reads might affect write-read timing and diagnostics.
  • Throughput and metrics output reveal whether stale-read workarounds are causing extra RUs, retries, or latency.
  • Key listing output, when used, proves access context but should be handled as sensitive operational evidence.

Mapped commands

Session token Azure CLI operations

adjacent 
az cosmosdb show --name <account-name> --resource-group <resource-group> --query consistencyPolicy --output json
az cosmosdbdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb sql container show --account-name <account-name> --resource-group <resource-group> --database-name <database-name> --name <container-name> --output json
az cosmosdb sql containerdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb sql container throughput show --account-name <account-name> --resource-group <resource-group> --database-name <database-name> --name <container-name> --output json
az cosmosdb sql container throughputdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb show --name <account-name> --resource-group <resource-group> --query locations --output json
az cosmosdbdiscoverDatabases
read-only Microsoft Learn 
az monitor metrics list --resource <cosmos-account-resource-id> --metric TotalRequests --interval PT1M
az monitor metricsdiscoverDatabases
read-only Microsoft Learn

Architecture context

Architecturally, a session token is a continuity signal between Cosmos DB and the application workflow. I care about it most in stateless, distributed, or multi-service designs: API gateways, background workers, mobile apps, and microservices that write and then read through different paths. The token should stay near the workflow that needs read-your-writes behavior, not be treated as a global cache key. Designs should define when SDK-managed behavior is enough, when manual propagation is required, how tokens are logged or redacted, and how partition keys shape the guarantee. The right test is a realistic write-read journey, not a database-only smoke test.

Security
Security impact is indirect but still worth handling carefully. A session token is not the same as an account key, SAS, or Microsoft Entra token, and it does not authorize access by itself. However, it can expose partition and consistency context, clutter logs with sensitive operational data, and mislead support staff if copied into tickets without redaction. Applications should avoid broad header logging, protect diagnostics, and never treat session-token possession as proof of identity. Real security still comes from network controls, authentication, authorization, key management, private endpoints, and least-privilege data access. Keep tokens out of customer-visible logs. Never log raw token values into shared support channels, durable traces, or customer-visible diagnostics.
Cost
Session tokens have no direct cost meter, but broken token handling can create expensive behavior. Applications may retry reads, issue broader queries, duplicate writes, or switch to stronger consistency because users report stale data. Each workaround can increase RU consumption, latency, and support labor. Correct token flow often fixes the user experience without changing account tier or throughput. Cost analysis should compare request charge, retry count, and query breadth before and after a session-token fix. The cheapest solution is usually preserving the intended session behavior rather than overprovisioning RUs or making every read stricter. Track retry storms separately from normal reads when token handling or region routing changes.
Reliability
Reliability impact is direct for workflows that need read-your-writes behavior. When session tokens are preserved, Cosmos DB can satisfy reads at or beyond the session’s observed write progress. When tokens disappear, users may see stale data until normal replication catches up, especially after client recreation, service hops, or regional reads. That can trigger duplicate actions and unreliable support experiences even when the database is healthy. Reliable systems test token flow through the actual request path, including gateways, async workers, mobile reconnection, and failover scenarios. SDK diagnostics should be part of the runbook, not an afterthought. Validate token propagation in every service hop that performs a write and dependent read.
Performance
Performance impact is tied to read path behavior. With session consistency, a read may need a replica that has reached the session-token progress, and the SDK can retry when a replica is behind. Correct token handling gives predictable user behavior with performance close to eventual consistency in many designs. Incorrect handling can cause confusing stale reads, duplicate UI refreshes, and extra queries. Overly defensive manual token use can also add complexity. Measure SDK diagnostics, latency percentiles, request charge, retry count, and partition-key access before changing consistency policy. The token is usually a clue, not the bottleneck itself. Measure token-aware flows under realistic concurrency, partition distribution, and gateway routing patterns.
Operations
Operators usually encounter session tokens during stale-read investigations, not routine account administration. The operational job is to gather account settings, region topology, container scope, partition keys, SDK diagnostics, and request correlation IDs. Because the token itself comes from the SDK, operators need developer cooperation and safe diagnostic logging. Runbooks should say how to reproduce the write-read sequence, which headers are safe to capture, and how to compare behavior across app instances. CLI evidence anchors the environment, while application logs show whether token state is retained, forwarded, or lost in the workflow. Keep partition key, consistency level, and sanitized token presence visible in request diagnostics.

Common mistakes

  • Treating a session token as an Azure resource that can be managed directly with CLI or ARM.
  • Logging full session-token headers into shared support tickets or customer-visible traces.
  • Recreating SDK clients per request and then blaming Cosmos DB for stale reads.
  • Passing tokens without preserving the correct partition and workflow context.
  • Switching to strong consistency before proving whether session-token flow is actually broken.