{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","type":"markdown"},"seo":{"title":"Development lifecycle","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com/"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"development-lifecycle","__idx":0},"children":["Development lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/how_mosaic_is_organized"},"children":["How Mosaic is organized"]}," for a primer, and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/understand_environments_regions_tenants"},"children":["Understand environments, regions, and tenants"]}," for how to choose an environment and region and plan your tenants."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Lifecycle"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At a high level, you build and iterate in the sandbox, promote your configuration to a pre-production tenant for validation, and then promote it to your production tenant for live traffic."]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n subgraph SANDBOX[\"Sandbox environment\"]\n DEV[\"Dev tenant
Build and iterate\"]\n end\n subgraph PRODUCTION[\"Production environment (e.g., US region)\"]\n PREPROD[\"Pre-production tenant
UAT, QA, validation\"]\n LIVE[\"Production tenant
Live traffic\"]\n end\n DEV -->|Promote changes| PREPROD\n PREPROD -->|Promote changes| LIVE\n","diagramHtml":"

Production environment (e.g., US region)

Sandbox environment

Promote changes

Promote changes

Dev tenant
Build and iterate

Pre-production tenant
UAT, QA, validation

Production tenant
Live traffic

","diagramHtmlDark":"

Production environment (e.g., US region)

Sandbox environment

Promote changes

Promote changes

Dev tenant
Build and iterate

Pre-production tenant
UAT, QA, validation

Production tenant
Live traffic

"},"children":["flowchart LR\n subgraph SANDBOX[\"Sandbox environment\"]\n DEV[\"Dev tenant
Build and iterate\"]\n end\n subgraph PRODUCTION[\"Production environment (e.g., US region)\"]\n PREPROD[\"Pre-production tenant
UAT, QA, validation\"]\n LIVE[\"Production tenant
Live traffic\"]\n end\n DEV -->|Promote changes| PREPROD\n PREPROD -->|Promote changes| LIVE\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"develop-and-test-in-the-sandbox","__idx":1},"children":["Develop and test in the sandbox"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/dev-tools/dev_tools_overview"},"children":["API Explorer"]}," to try out APIs without writing code."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/maintain_integration"},"children":["Maintain your integration"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/understand_environments_regions_tenants#pre-production-usage-limits"},"children":["Understand environments, regions, and tenants"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"promote-changes-safely","__idx":2},"children":["Promote changes safely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"understand-the-scope","__idx":3},"children":["Understand the scope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It helps to think of a tenant's contents as separate categories when planning a promotion:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/platform/migrate_to_mosaic"},"children":["Migrate to Mosaic"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommendations"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because environment data isn't carried across, some items—secrets, certificates, per-tenant client credentials, and authentication provider settings—aren't exported and must be created manually in the target tenant before you import."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"choose-a-promotion-mode","__idx":4},"children":["Choose a promotion mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Promotion runs in one of the following modes, chosen per entity type within your version data:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For step-by-step export and import procedures, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/version_management_procedures"},"children":["Run CI/CD flow"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-your-integration","__idx":5},"children":["Update your integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Promotion updates your Mosaic configuration, but your application must also point at the target environment. Before you go live in a new environment, update:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API base URL."]}," Switch your backend to the target region's host—for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.sbx.transmitsecurity.io"]}," in sandbox or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.transmitsecurity.io"]}," for US production. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/understand_environments_regions_tenants"},"children":["Understand environments, regions, and tenants"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SDK configuration."]}," Update the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseUrl"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serverPath"]}," in your web, iOS, and Android SDKs to match the target region."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client credentials."]}," Use relevant client ID and secret when authorizing API calls and SDK sessions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom domain."]}," In production, you may serve requests through your own ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/custom_domains"},"children":["custom domain"]}," instead of the default host, which also involves DNS and certificates."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices-for-working-with-multiple-developers-in-a-shared-tenant","__idx":6},"children":["Best practices for working with multiple developers in a shared tenant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order of priority:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Promote with selective mode"]},", so only your own reviewed changes move—not the whole tenant's state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For step-by-step export and import procedures, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/version_management_procedures"},"children":["Run CI/CD flow"]},"."]}]},"headings":[{"value":"Development lifecycle","id":"development-lifecycle","depth":1},{"value":"Develop and test in the sandbox","id":"develop-and-test-in-the-sandbox","depth":2},{"value":"Promote changes safely","id":"promote-changes-safely","depth":2},{"value":"Understand the scope","id":"understand-the-scope","depth":3},{"value":"Choose a promotion mode","id":"choose-a-promotion-mode","depth":3},{"value":"Update your integration","id":"update-your-integration","depth":3},{"value":"Best practices for working with multiple developers in a shared tenant","id":"best-practices-for-working-with-multiple-developers-in-a-shared-tenant","depth":2}],"frontmatter":{"markdown":{"toc":{"depth":3}},"seo":{"title":"Development lifecycle"}},"lastModified":"2026-09-27T11:00:20.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/deployment/development_lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}