> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization settings

> Set the Directorate’s identity, regional defaults, branding, and organization address without changing service data or access by accident.

Organization settings establish the shared context in which KayanOS operates. They identify the Directorate of Citizen Services, set defaults used by staff-facing screens, and define the organization address and visual identity. They do not grant a role, translate existing records, change a citizen request’s status, or make a restricted record visible.

Treat this page as a controlled administrative change. A designated organization administrator should own the change, and the service owner should review a change that affects language, time, or the organization address.

## Goal

Set an accurate organization identity and safe regional defaults, then test the result with a controlled staff workflow before relying on it in a published service.

## What each setting controls

| Area              | What it controls                                                  | What it does not control                                                     |
| ----------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Identity          | Display name, short description, country, employee band, and logo | A member’s role, a record owner, or a citizen-facing decision                |
| Regional defaults | First day of week, default timezone, and default language         | Translation of existing custom labels or conversion of stored dates/numbers  |
| Brand theme       | Approved primary color and organization visual identity           | The permissions or content of an application                                 |
| Subdomain         | The organization-specific KayanOS address                         | A custom short-link domain, email domain, or public-portal publication state |

The default language list is built from the organization’s active language records. Activate and quality-check a language before setting it as the organization default. Likewise, a default timezone is a shared starting value; service fields and event records can still carry their own approved timezone where the applicable feature supports it.

## Before you change a setting

1. Confirm that you are the organization owner or have the organization-settings authority assigned by your role and scope.
2. Write down the current value, why it is changing, the approving owner, and a safe reversal path.
3. For a language change, confirm that required Arabic and English titles, statuses, templates, and public text are ready. A default language does not translate unlocalized custom data.
4. For a timezone or work-week change, identify the services affected by dates, deadline rules, calendar views, or reports.
5. For a logo or theme change, prepare an approved asset and test it in both light and dark interface modes.
6. For a subdomain change, notify support owners in advance: staff bookmarks, saved links, portal links, and any approved integrations may need review after the redirect.

Use an approved non-production organization or a controlled maintenance window for the first test. Do not use a change of organization identity to disguise a tenant, move records, or work around a permission denial.

## Configure identity and regional defaults

Open **Administration → Organization settings**. Review the whole form before saving because its values form one organization-level profile.

1. Set the localized **display name** and **short description**. Enter a clear Directorate name in each active language that needs it; avoid a temporary project name or a citizen’s name.
2. Select the country and employee-size band that describe the organization. These are organization metadata, not staffing entitlements.
3. Choose the first day of the operational week. Confirm the choice with the team that uses attendance, schedules, and workload views.
4. Choose the approved default timezone. For a Syrian public-service directorate, select the approved local time-zone option, such as `Asia/Damascus` where that is the organization’s policy. Do not change it merely to make a single report look different.
5. Select a default language from the active language list. If Arabic is selected, verify right-to-left navigation, dates, numerals, custom entity titles, and public text after saving.
6. Upload or remove the organization logo only when the replacement has been approved. Confirm that it remains legible at the compact size used in navigation.
7. Save, then reopen the settings page and confirm that the persisted values are the values you intended.

Changing these defaults does not rewrite a record’s existing field values. For example, changing the default language does not translate the existing status **Decision review**, and changing the default timezone does not alter a saved event’s start time. Correct records through their own authorized workflow.

## Configure the brand theme

The organization theme is for recognizable, accessible presentation. Configure it separately from business content:

* Use the approved organization color or a valid custom hexadecimal color when your branding policy permits it.
* Review contrast in light and dark modes. A color that looks acceptable on a white background can make a button, chart, or focus state difficult to read elsewhere.
* Use a logo and visual identity that staff can recognize without exposing a citizen, service reference, or internal contact detail.
* Save one theme change at a time, then test Home, the sidebar, a form, and a public-facing page that the organization has explicitly published.

Branding is not a security boundary. It cannot hide sensitive data, restrict a user, or prove that a message or document was officially issued.

### Set Homepage hero images

The **Homepage hero images** control belongs to Organization settings. Upload separate light and dark images, then choose their position and size. Save, remove one theme’s image, or reset both only while the intended organization is active. These images brand the launcher-first Home; they do not define member shortcuts or a shared widget layout. Follow [Homepage](/admin/homepage) for the complete upload and validation procedure.

## Choose the organization interface style

**Interface style** changes the navigation and Home experience for everyone in the organization:

* **Modern** uses a launcher-first Home with global top navigation and is the safe default when no recognized style is saved.
* **Classic** keeps the previous Home experience with sidebar navigation.

This setting changes presentation, not routes, stored records, permissions, or the organization's brand theme. Choose it as an organization-wide operating change rather than a personal preference. Before saving, tell affected teams which navigation model they should expect.

After saving, reopen Home, an application workspace, a record detail page, a form, and the launcher with a controlled member. Test both English and Arabic/RTL and a smaller screen. If an unknown or removed style value is encountered, KayanOS falls back to Modern; do not depend on an unsupported metadata value to preserve a custom layout.

## Change the organization subdomain carefully

The subdomain is the organization’s KayanOS address. It has stricter consequences than a display-name edit because the browser redirects to the new origin after a successful save.

The form accepts a lower-case subdomain of 3–63 characters using letters, digits, and hyphens, with no leading or trailing hyphen. KayanOS checks availability before a changed value can be saved. Follow this sequence:

1. Choose a stable, approved short name. For example, use an organization-wide Directorate address rather than the name of one temporary service centre.
2. Enter the proposed value and wait for the availability result. Do not treat an untested name as reserved.
3. Ask a second administrator to verify spelling, ownership, and the intended address before saving.
4. Save the change. The current browser session redirects to the new organization address.
5. At the new address, sign in again if required, open a controlled request such as `CSR-2026-00042`, and verify that the organization context, language, and navigation are correct.
6. Update approved bookmarks and portal/integration configuration only after the new address works. Do not circulate an unverified address to citizens or staff.

Changing the organization subdomain is different from configuring a custom short-link domain or verifying an email domain. Those systems have separate DNS and policy requirements; see [Domains and channels](/admin/domains-and-channels).

## Directorate scenario

The Directorate of Citizen Services prepares a bilingual launch for its **Citizen Service Request** service. The administrator sets the Arabic and English display names, activates Arabic before selecting it as a default option, selects the approved local timezone, and checks that the week starts according to the Directorate’s published schedule. The service owner then opens the same controlled request in both interface languages.

Expected result:

* staff see the approved organization identity and logo;
* Arabic screens render right-to-left without changing the stable field key or serial reference `CSR-2026-00042`;
* a calendar event and a request record retain their stored values; and
* no member gains new access just because a regional default changed.

Only after this check should the team consider a subdomain or brand-theme change. Keep the service configuration, organization profile, and role review as separate approved changes.

## Validation and safe rollback

| Test                                       | Expected result                                                                                     | Safe response if it fails                                                                                                       |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Save a localized display name              | The name reappears after reopening the page                                                         | Restore the last approved name and record the correction                                                                        |
| Switch to Arabic                           | RTL direction and interface labels change after reload; custom content stays as configured          | Fix the language record or custom translations before making Arabic the default                                                 |
| Review a known event after timezone review | The existing event remains intact; the setting is not a bulk date conversion                        | Correct the event only through its own authorized edit flow                                                                     |
| Upload an approved logo                    | It is visible and legible in navigation                                                             | Revert to the prior approved logo; do not use a personal image as a substitute                                                  |
| Switch interface style                     | Home and navigation use the selected organization-wide model after reload; access remains unchanged | Restore the last approved style and verify both language directions before retrying                                             |
| Propose a subdomain                        | Availability is explicitly shown before saving                                                      | Choose a different approved name; do not retry by inventing punctuation or uppercase characters                                 |
| Save a subdomain change                    | The browser reaches the new origin and the correct organization context loads                       | Stop sharing links, restore the approved address through the authorized administrator, and investigate DNS/deployment ownership |

## Troubleshooting

| Symptom                                            | Check first                                                                                         | Safe response                                                                                       |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Save is unavailable                                | Organization-setting permission, required values, and validation messages                           | Ask the authorized administrator to review the smallest missing authority                           |
| A language is not offered as a default             | The language record is active and has a valid code/name                                             | Activate and test the language first; do not enter an unsupported code in a record                  |
| Arabic controls look wrong                         | Reload completed, the language direction is RTL, and custom labels have Arabic text                 | Capture the specific screen and correct the language/custom-label configuration                     |
| A logo upload fails                                | File selection, upload result, and approved asset policy                                            | Keep the prior logo and retry with a compliant approved file                                        |
| The saved interface looks unchanged                | Reload, current organization, persisted style, and whether the page uses shared organization chrome | Reopen a supported route and verify the saved organization before changing unrelated theme settings |
| A subdomain is rejected                            | Length, lower-case format, hyphen position, and availability result                                 | Select another approved name; do not bypass the address check                                       |
| Staff land on an unexpected address after a change | The new subdomain, bookmarks, and organization context                                              | Use the approved organization address and notify the change owner before changing any data          |

## Related guides

* Maintain active languages and currencies in [Languages and currencies](/admin/languages-and-currencies).
* Give administrators and service teams only the access they need in [Roles and scopes](/admin/roles-and-scopes).
* Configure Home hero images and understand personal favorites in [Homepage](/admin/homepage).
* Diagnose a missing setting or denied action in [Permissions and availability](/reference/permissions-and-availability).

![KayanOS organization settings for the Directorate of Citizen Services.](https://kayanos.app/docs-images/en/admin/organization-settings.png)