Tenant Setup and Configuration

Multi-Tenant Architecture

VersionForge uses a multi-tenant architecture where each customer or business unit operates in a fully isolated environment. A tenant is the top-level boundary for all data, connections, sync profiles, credentials, and user permissions. Data in one tenant is never visible to or accessible from another tenant.

This isolation applies to:

• Sync data -- Snapshots, diffs, and loaded records are scoped to the tenant.
• Credentials -- Connection credentials are encrypted per-tenant with tenant-specific keys.
• Configuration -- Field mappings, transform rules, and approval workflows are tenant-specific.
• Audit logs -- Every action is logged within the tenant's audit trail.

Creating a New Tenant

1. Access the platform admin console

   Log in as a platform administrator (not a tenant-level admin). Navigate to Platform Admin > Tenants in the top-level navigation. This console is only visible to users with the platform_admin role.

2. Click New Tenant

   Click the New Tenant button. The setup wizard opens with four configuration sections.

3. Basic information

   Enter the following:

   • Tenant name -- A human-readable name for this tenant (e.g., "Acme Corp" or "EMEA Business Unit"). This appears in the tenant switcher and audit logs.
   • Tenant slug -- A URL-safe identifier used in API paths and internal references (e.g., acme-corp). This cannot be changed after creation.
   • Primary contact email -- Used for critical system notifications (credential expiry, billing alerts).

4. Admin credentials

   Create the first admin user for this tenant:

   • Admin email -- The email address for the initial tenant administrator.
   • Temporary password -- Set an initial password. The admin will be prompted to change it on first login.

   This user receives the tenant_admin role, which grants full access to all tenant features including user management, credential configuration, and sync profile creation.

   The initial admin credentials are sent via email. Make sure the admin email is correct before proceeding -- there is no way to recover the initial password if the email bounces.

5. Tenant settings

   Configure the default settings for this tenant:

   • Default timezone -- Used for scheduled sync times and dashboard timestamps (e.g., America/New_York).
   • Fiscal calendar -- Select the fiscal year start month and period structure (monthly, 4-4-5, 4-5-4, or 13-period). This setting affects the GL History Loader and period-based reporting.
   • Notification preferences -- Choose which events trigger email notifications to the primary contact: sync failures, credential warnings, cross-check failures.

6. Review and create

   Review the configuration summary and click Create Tenant. VersionForge provisions the tenant's isolated environment, generates encryption keys, and sends the admin welcome email.

Post-Creation Setup

After the tenant is created, the tenant admin should complete these steps:

1. Log in and change the temporary password.
2. Add connections -- Configure source and target system connections under Connections > New Connection.
3. Invite additional users -- Add team members under Settings > Users with appropriate roles (admin, editor, reviewer, read-only).
4. Configure alerts -- Set up Slack and email alert channels under Settings > Alerts. See Alert Configuration.

Tenant-Level Settings Reference

| Setting | Location | Description | |---------|----------|-------------| | Timezone | Settings > General | Default timezone for schedules and timestamps | | Fiscal calendar | Settings > General | Fiscal year start month and period structure | | Data retention | Settings > General | How long snapshots and run logs are retained (default: 90 days) | | Auto-approve rules | Settings > Safety Gate | Rules for automatically approving low-risk changes | | Notification channels | Settings > Alerts | Slack webhooks and email recipients | | API tokens | Settings > API Tokens | Tokens for programmatic access |