Mosaic runs your integration within a few clear boundaries: an environment (production or sandbox), a region where your data is stored, and one or more tenants that hold your configuration and identities. This guide explains each one and how to plan them, so you can set up your integration correctly from the start. For a quick primer on how these pieces fit together, see How Mosaic is organized.
Mosaic is delivered through two environment types, each serving a distinct role in your development lifecycle.
Production is for live, customer-facing traffic, and enforces your identity, verification, and fraud prevention policies. Production is available in several regions, so you can store your data where your business location, data residency, and compliance requirements dictate:
- United States (US)
- European Union (EU)
- Canada (CA)
- Australia (AU)
- Japan (JP)
Sandbox is for development and early-stage testing only. It's hosted in the US, supports all Mosaic APIs and SDKs, and must never be used for live traffic.
Your choice of environment and region determines the base URL for API calls and the Admin Portal you log in to:
| Environment | Region | Base URL |
|---|---|---|
| Sandbox | US | api.sbx.transmitsecurity.io |
| Production | US | api.transmitsecurity.io |
| Production | EU | api.eu.transmitsecurity.io |
| Production | CA | api.ca.transmitsecurity.io |
| Production | AU | api.au.transmitsecurity.io |
| Production | JP | api.gasne1-ts01.transmitsecurity.io |
Examples in Mosaic documentation are typically based on the US production base URL (api.transmitsecurity.io). Check the correct base URL for your region and adjust code snippets as needed. For the full base URL structure, see the API reference. For all portal URLs and how to switch tenants, see Access to Admin Portal.
Unless your commercial agreement with Transmit Security specifies otherwise, you're entitled to:
- Two production tenants
- One sandbox tenant
The recommended way to use them:
- One production tenant carries live, customer-facing traffic and final validation only.
- The second production tenant, paired with the sandbox tenant, covers pre-production work—development, UAT, QA, and configuration validation.
Keep live and pre-production work in separate tenants—mixing them in one tenant increases operational risk.
The term sandbox is often used for two different things: Mosaic's Sandbox environment, Transmit Security's US-hosted pre-release environment, and your team's own development and testing setup.
To avoid confusion, refer to your second production tenant used for development and testing as a pre-production tenant. It runs in a production environment, separately from Mosaic's Sandbox.
Additional tenants add real cost and operational complexity, and usage is tracked and enforced per production tenant—not aggregated across tenants. Before adding a tenant, model your needs with the tools designed for it:
- Model organizational complexity with apps and organizations. Give each business unit, subsidiary, market, or channel its own app inside a single tenant, with its own isolated user pool and journeys—without the cost of a separate tenant. See How apps and clients work. For B2B products, model the external business entities that access an app as organizations, each with its own members and roles.
- Manage team access with RBAC. Use role-based access control to control who can view or edit configuration in a tenant.
- Centralize identity and fraud signals in one tenant per region. Splitting them reduces detection accuracy and adds integration and operational overhead.
Add tenants beyond the default only for a genuine regulatory, data-residency, or release-process reason—and treat it as an architecture decision made with your account team, not a workaround for a process problem. If a team's development volume genuinely can't be managed within the default model, a second production tenant used purely as a pre-production gate is the supported way to add isolation.
Usage is tracked and enforced against your production tenant, which is the single source for commercial reporting, billing, and renewals. Pre-production tenants are for validation and testing, not sustained workloads. Unless explicitly agreed otherwise, pre-production usage is limited to:
| Metric | Pre-production limit |
|---|---|
| Monthly Active Users (MAUs) | Up to 100 per month |
| Detection & Response requests | Up to 10,000 per year |
| Identity Verifications | Up to 100 per year |
| Journey invocations | Up to 10,000 per year |
Sustained usage beyond these limits may require commercial alignment and may result in additional charges. If you anticipate higher pre-production usage, engage your Technical Account Manager or Account Executive proactively.
Within a tenant, an app holds the configuration for one integration—branding, authentication settings, and more—and requires at least one client. Each client represents a specific implementation with its own credentials and settings.
As a best practice, use one client per integration. For example, use a web client for your browser app, a native client for your Android app, and a separate native client for your iOS app. Clients of the same app share user sign-ups, so a user who registers on the web app doesn't need to register again in the mobile app.
Use apps to draw clean boundaries for subsidiaries, lines of business, markets, and channels, each with its own isolated user pool—all within a single tenant. To get started, see Create applications and How apps and clients work.
If you're building a B2B product, add a second layer of hierarchy with organizations. An organization represents an external business entity—a customer company, partner, branch, or supplier—that accesses your app, and it holds its own members and roles. Organizations can also be nested as parent and child organizations, so one business entity can manage a set of sub-organizations within a scope you control. This lets you model complex customer structures inside a single tenant, without a separate tenant per customer. See B2B Identity main concepts.
Manage who on your team can view or edit configuration using role-based access control. Mosaic provides three default roles—Global admin, Global reader, and Support—plus custom roles you build from a permission tree, following the principle of least privilege.
Two things to plan around:
- RBAC controls Admin Portal permissions—broadly, what a person can view versus edit. It's not a tool for restricting specific users to specific journeys or connections; that's an organizational-boundary question, and apps are the right mechanism.
- Roles are scoped per tenant and aren't synced across tenants. A "Reviewer" role in your pre-production tenant and a "Reviewer" role in production are two separately defined things that happen to share a name.
Define a consistent role pattern—for example, an Engineer role scoped to pre-production, a Reviewer role with read access to production and edit access to pre-production, and a Release Owner role with edit access to production—document it once, and recreate it deliberately in every tenant, since the platform won't keep them in sync for you.