Overview

App Overrides let you define named configuration values that can vary by environment, tenant, or user role — all within a single application record. Instead of duplicating an app for staging versus production, or cloning it for every customer in a white-label deployment, you declare override keys and supply different values for each context. The app reads the correct value at runtime based on which context the current session falls into.

Overrides are a configuration layer on top of your app, not a separate app. Every page, component, and data source is shared across all override contexts; only the values you explicitly override differ between them. This keeps your maintenance surface small and ensures a bug fix or feature change in the builder rolls out to every override variant on the next publish.

Note: Overrides are not permissions. Permissions control whether a user can see something. Overrides control what value a configuration key holds for a given context. They are complementary features that are often used together — for example, an override supplies the correct API base URL for the user's tenant, while permissions gate which pages that tenant's users can access.

Types of Overrides

Three override types are available, each scoped to a different dimension of runtime context.

Environment Overrides

Environment overrides supply different values for the same key across your deployment environments — typically development, staging, and production. Common use cases include:

• API base URLs — point staging at your staging backend and production at your production backend without changing the data source configuration itself.

• Feature flags — enable an in-progress feature in development and staging while keeping it off in production until it is ready to ship.

• Connection IDs — use a sandboxed connector in staging and the live connector in production.

• Log verbosity — enable detailed console logging in development, suppress it in production.

Environment overrides are resolved based on the deployment environment the app is running in, which is set at the workspace or deployment configuration level — not at runtime by the user.

Tenant Overrides

Tenant overrides are for white-label or multi-tenant SaaS deployments where each customer organisation (tenant) needs a variation of the app. Values are keyed to the authenticated user's tenant ID and resolved at login. Common use cases include:

• Branding — supply each tenant's logo URL, primary color token override, and header text so the app visually matches their brand without separate app records.

• Data scope — supply tenant-specific filter values injected into data source queries so each tenant only sees their own records.

• Feature sets — enable or disable pages or features for specific tenants based on their subscription tier, using tenant-scoped feature flags.

• Locale defaults — set the default language, date format, and currency symbol per tenant.

Tenant override values are managed in the Overrides configuration panel and can also be ingested from an external tenant configuration API by pointing a data source at the override values endpoint.

User-Role Overrides

Role overrides supply different values based on the authenticated user's role within the app. They complement the Permissions system by handling configurational differences between roles rather than visibility differences.

• Page visibility soft-controls — where you want a role to see a page but with reduced capabilities (e.g., a read-only API endpoint override), use role overrides rather than block permissions.

• Dashboard defaults — different default date ranges or metric groupings for different roles.

• Navigation labels — role-specific terminology in navigation items without separate navigation configurations.

Configuration

Overrides are configured in the Builder Settings panel.

1. Open Builder Settings: From inside the Application Builder, click the gear icon in the top bar to open Builder Settings.

2. Navigate to Overrides: Select App Settings → Overrides in the settings panel. The Overrides section lists all currently defined override keys.

3. Add an override key: Click Add Override. Provide the key name, select the type (Environment, Tenant, or Role), enter a default value, and add per-context values.

4. Save and use in bindings: Click Save. The override key is now available in the binding picker across the entire app.

Override Schema

Each override is defined by the following properties:

Schema Example

The following example shows an environment override for an API base URL, with different values for staging and production and a local development default:

{ "key": "apiBaseUrl", "type": "env", "defaultValue": "http://localhost:3001/api", "environments": { "staging": "https://api-staging.acme.com/v2", "production": "https://api.acme.com/v2" } }

And a tenant override for the primary brand color used in a dynamic theme swap:

{ "key": "tenantPrimaryColor", "type": "tenant", "defaultValue": "#0066CC", "tenants": { "acme-corp": "#E53935", "initech": "#2E7D32", "umbrella-co": "#6A1B9A" } }

Accessing Overrides in Bindings

Override values are available anywhere in the app that accepts a binding expression. Use the app.overrides namespace followed by the override key:

{{app.overrides.apiBaseUrl}} {{app.overrides.tenantPrimaryColor}} {{app.overrides.featureFlagBeta}}

The most common places to bind overrides:

• Data source base URL — bind the base URL field of a REST data source to {{app.overrides.apiBaseUrl}} so staging and production point to different backends automatically.

• Component visibility — bind a component's Visible property to {{app.overrides.featureFlagBeta}} to show it only when the flag is true for the current environment or tenant.

• Theme token override — pass {{app.overrides.tenantPrimaryColor}} to a dynamic token setter action to visually re-brand the app for each tenant at login.

• Navigation label — bind a navigation item's label text to an override key that holds role-specific or tenant-specific wording.

Tip: Override values are read at app load time. Changing an override key's value for an environment or tenant does not affect active user sessions — users see the new value on their next page load or app restart. Plan override changes accordingly, especially for production environment changes.

Override Precedence

When a session falls into multiple override contexts — for example, a user has a specific role and belongs to a specific tenant — the runtime applies overrides in the following order, from highest to lowest priority:

If a role override exists for key apiBaseUrl for the current user's role, that value wins regardless of the tenant or environment. If no role override matches but a tenant override matches, that value is used. And so on down to the default.

Warning: Each override key has a single type. A key is either an environment override, a tenant override, or a role override — not a combination. To achieve complex cross-dimensional variations (e.g., different values per environment and per tenant), create two separate keys and combine them in a binding expression or a JavaScript function on the data source.

Common Use Cases

SaaS Multi-Tenant Apps

In a SaaS product built on UnifyApps, every customer organisation is a tenant. Use tenant overrides to supply each customer's logo URL, color palette, and data scope parameters. The app itself is deployed once; tenants share the same codebase but see their own brand and data.

Workflow:

1. Define tenant override keys: tenantLogoUrl, tenantPrimaryColor, tenantDataScopeId.

2. Bind the navigation logo's src to {{app.overrides.tenantLogoUrl}}.

3. Bind data source filter parameters to {{app.overrides.tenantDataScopeId}}.

4. When onboarding a new tenant, add their tenant ID and values to each relevant override key's tenants map.

Environment Promotion

Teams working with a dev/staging/production pipeline use environment overrides to prevent accidental data mutations. The staging environment's apiBaseUrl override points at the staging backend; the same app published to production automatically uses the production URL — no code change, no separate app record, no risk of a developer leaving a staging URL hardcoded.

Feature Flags Per Environment

Gate new features behind environment overrides before they are ready for production. A boolean featureFlagNewDashboard override set to true in staging and false in production controls a component's Visible property. Release the feature by flipping the production value to true — no republish required if the override value change is picked up at the configuration layer.

Related Pages

• App Configuration — full reference for all Builder Settings sections.

• Runtime & Access — environment setup and deployment targets.

• Permissions — role-based visibility for pages and blocks.