# Company administration

## Create a company and its first administrator

1. Sign in as Super Admin and open **Create tenant**.
2. Enter the company name, unique workspace slug, timezone and subscription plan. Shared SaaS is the existing local installation arrangement; it requires no cloud or DNS setup.
3. Choose whether the company may create branches. Set optional maximum branches, company users and employees. An empty numeric field adds no extra company cap. Users always remain capped by the subscription plan as well.
4. Enter the administrator's name, unique email and a password of at least 12 characters including uppercase, lowercase, numbers and symbols. Confirm the password and select **Provision workspace**.
5. The company, subscription, enabled modules, three roles and administrator are created together. A validation failure leaves no partially created company. OCR starts disabled.
6. Give the administrator their email and password through your usual secure channel. Their first login requires authenticator enrollment before entering their workspace. Existing local demo account exceptions remain limited to those demo accounts.

Use **Tenant directory > Manage > Company capacity controls** to change limits later. All registered users, inactive employees and inactive branch records count. Disabled accounts still occupy a user place. Numeric limits cannot be below existing usage. Disabling branch creation preserves existing branches and permits editing their history. Employee CSV imports are atomic: a file exceeding capacity imports no employees. API and manual creation follow the same service checks.

## Company roles

New companies start with three company-owned roles:

| Role | Default access |
| --- | --- |
| Company Admin | Company modules, configuration and account administration |
| Employee | Own employee profile, documents, attendance, payslips and self-service requests through the employee workspace, plus form submission |
| Manager | Employee self-service plus operational viewing, attendance/leave approvals, direct-report decisions, performance management and reports; no Company Settings or account/role administration |

Module entitlements and existing record-level policies still apply to every role. A preset is a starting point, not a commercial module entitlement. Manager viewing and performance capabilities may include company-wide information; review and tailor them before assigning the role.

Open **People & access** to assign these roles or expand a role to edit capabilities. Use the capability search to find a specific module. **Load preset capabilities** lets you replace the current checkbox selection with a preset; review and save to apply it. **Create a custom role > Start from a predefined role** copies a preset into the new role form; you can change its selected capabilities before saving. Company Admin retains its name, Company Settings and account/role administration capabilities to prevent administrator lockout; its other capabilities are editable. Customized roles are preserved by later phase setup commands. Existing specialized/custom roles and assignments are retained.

SSO is currently removed from the Company Settings navigation and section access. Existing integration services are retained for compatibility. API access and webhooks remain optional company connections.

## Super Admin settings and email

Open **Platform settings** for the installation overview, **Email & SMTP**, and settings history. Company access, subscriptions, plans, quotas, modules and per-company OCR controls remain in the tenant directory and management pages. Server secrets and database credentials remain in the server environment.

Platform SMTP is separate from every company's SMTP configuration. It sends application password-recovery messages for platform and company accounts. Company reminder/notification emails continue to use the company's own connection.

1. Open **Platform settings > Email & SMTP** and confirm your password if requested.
2. Enter a public SMTP hostname, username, password and sender. Choose STARTTLS on port 587 or implicit TLS on port 465. TLS and certificate checks are mandatory. Private/reserved network destinations are blocked, with DNS checked and the destination pinned on every delivery.
3. Keep delivery **Disabled**, save, then optionally select **Send test to my account**. This immediately sends one test only to the signed-in Super Admin's email; an arbitrary recipient cannot be supplied.
4. Enable **Platform email delivery** after confirming the test. No email is sent merely by saving a disabled connection.

Credentials are encrypted in the database. A blank password preserves the saved one; changing the host or username requires re-entering it. Passwords never appear in rendered settings, validation old input or settings history. While platform delivery is disabled, recovery messages go to Laravel's private mail log. Enable SMTP before relying on email-based recovery on a hosted installation. No external SMTP delivery was attempted during automated verification; transport behavior is tested with controlled fakes.

## Upgrade

Back up the existing database and run `php artisan migrate --force`, then `npm run build`. The new platform mail and audit tables explicitly use InnoDB; existing tenant/role tables keep their engines. Company caps default to the previous behavior for existing companies (branches allowed, no extra numeric cap, plan user cap retained). No company records are deleted or reset. OCR remains disabled unless Super Admin explicitly enables it. The app remains Docker-free and needs no Cloudflare configuration.

Verification results are recorded in [Company administration verification](COMPANY_ADMINISTRATION_VERIFICATION.json). The five browser checks include real MFA enrollment and role-preset editing in the isolated browser database. Seven focused administration tests pass on both SQLite and MySQL. The full regression suite passed with four existing environment-specific skips; the additional password-broker integration test passed separately. All 102 live application tables were verified as InnoDB, OCR and platform SMTP remained disabled, and original business records were preserved.