Configuration Ownership
Choose where an App setting belongs and how to read host settings through the SDK.
Configuration Ownership
Choose where the value belongs
Keep an App's business settings in App-owned tenant data behind an authorized API. Use SDK contracts for host-owned settings. Deployment credentials and process configuration belong to operators, not to an App form.
| Value | Owner and change path |
|---|---|
| Database address, deployment service credential, signing secret | Deployment environment or secret store; operator rollout |
| Runtime default | Versioned Core configuration |
| Supported live platform override | Central administration through its approved setting surface |
| Tenant business timezone or locale | Tenant settings with host validation and authorization |
| App-specific behavior or preference | App-owned model, validation, and settings UI |
To publish an App settings destination, follow Add a settings page. To configure a host, use Environment Variables.
Read a host setting
Inside an App handler running in a tenant context, resolve the public service:
use Nexia\Tenancy\Contracts\TenantSettings;
$timezone = app(TenantSettings::class)->businessTimezone();TenantSettings is the SDK contract; Core binds its implementation. Do not query
Core's settings models or reproduce its storage keys in your App. The contract
is defined in packages/app-sdk/packages/laravel/src/Tenancy/Contracts/TenantSettings.php.
Design an App setting
- Define the App-owned value and its validation rules.
- Persist explicit tenant choices in App-owned data.
- Protect reads and changes with the App's permission and record rules.
- Publish a settings destination through the navigation contract.
- Use defaults only when the tenant has no explicit choice.
A settings destination does not supply persistence, authorization, or automatic configuration merging. The App implements those. See Add a protected API for the backend and Build an App screen for the UI.
Understand when changes take effect
Environment and cached boot configuration can require deployment and worker
restart. Supported live settings follow their owning runtime's update rules.
A tenant setting is product data, not a reason to rewrite .env or change another
tenant's preferences.
Do not overwrite explicit tenant values when releasing new defaults. If a data migration must change their meaning, plan the upgrade in Release an App.
Never include secrets in browser bundles or return stored secrets in ordinary read responses. Supported credential-management surfaces, such as tenant BYOK and SSO, may accept administrator input and store credentials through their protected server-side flow. Do not build a generic App setting to bypass that flow. Optional service settings are consumer-specific: search, Agent screen lookup, and import header matching do not share an implicit provider or failure policy. Use their entries in Environment Variables, Search Configuration Profiles, and Enable the Agent Gateway.