Development lifecycle

This guide walks you through how you develop, test, and release with Mosaic—working safely in the sandbox, then promoting configuration between tenants. Before you start, make sure you're familiar with how Mosaic is structured: see How Mosaic is organized for a primer, and Understand environments, regions, and tenants for how to choose an environment and region and plan your tenants.

Use the sandbox to develop and test your integration without affecting data or applications in production. It supports all the functionality provided by Mosaic APIs and SDKs, and it's also where you can use the API Explorer to try out APIs without writing code.

The sandbox is also your window into upcoming changes. All platform changes—including breaking changes—are deployed to sandbox before they reach production, giving you time to review release notes, test your integration, and validate behavior before a change rolls out to your live traffic. For details, see Maintain your integration.

Keep in mind that the sandbox is hosted in the US only, isn't designed for live traffic, and is subject to pre-production usage limits. See Understand environments, regions, and tenants.

As your configuration matures, you'll move it from one tenant to another—for example, from a development tenant hosted in sandbox to a pre-production (UAT) tenant in a production environment, and finally to production tenant with your live traffic.

It helps to think of a tenant's contents as separate categories when planning a promotion:

• Version data: The configuration that moves between tenants as a unit. It spans all Mosaic services, including journeys, sub-journeys, external connections, and typed lists, as well as applications, clients and client roles, user schema and user groups, service providers, resources, SSO configuration, and roles and role groups.
• Environment data: Keys, credentials, certificates, and other environment-specific values. These are managed per environment and never carried by value across tenants: only their aliases are exported, and the target tenant must already contain the actual values.
• Identity store: Users, devices, and runtime records generated by running flows. This stays where it's generated and is never part of a promotion. If needed, users are migrated separately. See Migrate to Mosaic.
• Recommendations, identity verifications: Recommendations produced by Fraud Prevention and Identity Verification results always stay in the tenant where they originated and are never part of a promotion.

Promotion runs in one of the following modes, chosen per entity type within your version data:

• Full—replaces the target's exported version data with the package and removes version data in the target that the package doesn't include. Use it for initial environment setup, cloning that configuration, or disaster recovery. Only the version data the export carries is replaced. Environment data values, the identity store, recommendations, identity verification results, and fields excluded from export are not part of the copy.
• Partial—scopes the promotion to journeys, sub-journeys, external connections, and typed lists. Identity management data in the package, such as clients, user schema, and SSO configuration, is still applied in full. You can mix:
  • Selective—promotes only the entities you choose and leaves everything else in the target untouched. Nothing is deleted, even if it's absent from what you're promoting. This is the default for incremental releases.
  • Sync—makes the target match the source exactly for the entity types you choose, including deletions. Use it deliberately when you want full alignment for a specific entity type—for example, keeping external connections identical across environments—without forcing a full-tenant move.

Because you choose the mode per entity type, you can mix them in a single promotion. For example, you can sync journeys while staying selective on external connections.

How often you promote—and in which mode—should follow your team's development practices. Teams iterating quickly often promote selectively and frequently, so each reviewed change moves on its own. Release-based teams tend to batch changes and promote on a fixed cadence, using full or sync mode at milestones to realign environments.

Promotion updates your Mosaic configuration, but your application must also point at the target environment. Before you go live in a new environment, update:

• API base URL. Switch your backend to the target region's host—for example, api.sbx.transmitsecurity.io in sandbox or api.transmitsecurity.io for US production. See Understand environments, regions, and tenants.
• SDK configuration. Update the baseUrl or serverPath in your web, iOS, and Android SDKs to match the target region.
• Client credentials. Use relevant client ID and secret when authorizing API calls and SDK sessions.
• Custom domain. In production, you may serve requests through your own custom domain instead of the default host, which also involves DNS and certificates.

When several developers share a tenant, the most direct way to avoid collisions is selective promotion: it moves only the entities you've actually changed and leaves everything else—including other developers' in-progress work—untouched.

Process discipline helps, but it has a real limit worth knowing going in. Assigning ownership by journey, or decomposing large journeys into smaller sub-journeys and shared components, reduces how often two people reach for the same object—it doesn't guarantee isolation. A sub-journey or external connection can be reused across multiple unrelated flows, the way a function is reused across a codebase, so two developers who each own a different top-level journey can still end up editing the same shared piece at the same time.

In order of priority:

1. Promote with selective mode, so only your own reviewed changes move—not the whole tenant's state.
2. Assign ownership by journey or component to reduce how often two people reach for the same object, understanding this won't fully prevent collisions on shared sub-journeys or connections.
3. Layer external version control on top. Export version data and manage and review it in a Git-like workflow—including PR review and conflict handling for anything shared—before promoting into a shared tenant.

Where a team's development volume genuinely can't be managed this way even with selective promotion in place, a second production tenant used purely as a pre-production/validation gate is the supported way to add further isolation—not an unbounded number of additional tenants.

For step-by-step export and import procedures, see Run CI/CD flow.