> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tarvah.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Client Onboarding
> Onboard new clients to the Tarvah BI platform — via UI or API
## Overview
Client onboarding creates all the resources a new client needs to run BI reports on their data:
1. **Snowflake Connection** — data source credentials for the client's schema
2. **Semantic Model** — client model that inherits from the Alpha Core model
3. **Virtual Data Mart (VDM)** — bridge between the semantic model and the Snowflake connection
4. **Dashboard** (optional) — auto-generated facade with core report charts
The onboarding flow is available in three ways:
Admin-only multi-step wizard in **Settings > Client Onboarding**
Upload an exported onboarding JSON file from the Client Onboarding UI
Single `POST /v1/sdk/client/onboard` call that orchestrates everything
***
## Prerequisites
Before onboarding a new client:
* The client's **Snowflake schema and tables** must already be provisioned by Data Ops (e.g., `DEF_SCHEMA` with `FCT_POSITION_SECURITY_LEVEL`, `DIM_SECURITY`, `DIM_ACCOUNT`)
* An **Alpha Core semantic model** must exist (this is the model all clients inherit from)
* If row-level security is needed, the **AUTH tables** (`ALPHA_USER_SCOPE`, `ALPHA_SCOPE_DEFN`, `ALPHA_FUND_AUTH`, `ALPHA_SERVICE_AUTH`) must be seeded with the client's scope data
***
## Via Settings UI
Navigate to **Settings > Client Onboarding** (visible to admins only).
### Step 1: Client Details
Enter the unique client identifier (e.g., `DEF`), display name, and optional description.
### Step 2: Data Source
Configure the Snowflake connection:
* Account URL
* Warehouse, Database, Schema
* Service account credentials
Click **Test Connection** to validate before proceeding.
### Step 3: Model & Dashboard
* Select the core model to inherit from
* Toggle row-level security
* Optionally enable a starter dashboard
### Step 4: Review & Create
Review all settings and click **Create Client**. The system will:
1. Create the Snowflake connection record
2. Create the client semantic model (inheriting from core)
3. Create and publish the Virtual Data Mart
4. Deploy the dashboard (if selected)
5. Register the client in the client registry
A progress indicator shows each step completing in real time.
***
## Via Import
Navigate to **Settings > Client Onboarding** and click the **Import** button in the toolbar. Select an exported onboarding JSON file (e.g., `onboarding-DEF.json`). The system will automatically:
1. Create the client semantic model (inheriting from core)
2. Create and publish Virtual Data Mart(s)
3. Deploy dashboards with all experiments and facades
4. Register the client in the client registry as `ACTIVE`
This is the recommended approach when transferring a client configuration from one platform to another without writing code.
***
## Via API
The onboarding API is available as an SDK endpoint at `POST /v1/sdk/client/onboard`. It supports both **API key authentication** and **browser session authentication**.
### Onboard a New Client
```bash API Key Auth theme={null}
curl -X POST https:///v1/sdk/client/onboard \
-H "Authorization: Bearer trvh_sdk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"clientId": "DEF",
"clientName": "Client DEF Corp",
"connectionId": "D2026A00042",
"externalIdKey": "CRD_ALPHA_CORE",
"coreModelId": "SM2026A00001",
"vdm": [
{
"name": "Main VDM",
"vendor": "SNOWFLAKE",
"selectedColumns": [],
"joinConfiguration": [],
"measureConfiguration": [],
"expressionConfiguration": []
}
],
"dashboards": [
{
"name": "DEF Dashboard",
"templateType": "realEstate",
"category": ["BI"],
"sections": [
{
"name": "KPIs",
"topSection": true,
"charts": [
{"title": "Total AUM", "type": "kpi", "measures": [{"field": "MARKET_VALUE", "aggregation": "sum"}], "dimensions": ["PERIOD"]}
]
}
]
}
],
"security": { "enabled": true }
}'
```
```bash Browser Session Auth theme={null}
curl -X POST https:///v1/sdk/client/onboard/ \
-H "Content-Type: application/json" \
-H "CTN: " \
--cookie "LASID=;ATN=;RTN=" \
-d '{ ... }'
```
### Response
```json theme={null}
{
"success": true,
"status": "COMPLETED",
"client": {
"clientId": "DEF",
"clientName": "Client DEF Corp",
"connectionId": "D2026A00042",
"modelId": "SM2026A00004",
"vdmIds": ["V2026A00109"],
"facadeIds": ["F2026A00018"],
"experimentIds": ["E2026A00042"],
"coreModelId": "SM2026A00001",
"status": "ACTIVE"
}
}
```
### Idempotency
Calling the onboarding endpoint for a client that already exists returns the existing record with `status: "ALREADY_EXISTS"` instead of creating duplicates.
### Rollback
If any step fails, all previously created resources are automatically cleaned up and a `FAILED` registry entry is saved for audit purposes.
See the full [API reference](/api-reference/client-onboard) for detailed field documentation.
***
## Client Registry
After onboarding, clients appear in the **Client List** view (Settings > Client Onboarding).
### List Clients
```bash theme={null}
curl https:///v1/bi/admin/clients/ \
-H "CTN: " \
--cookie "LASID=;ATN=;RTN="
```
### Get Client Details
```bash theme={null}
curl https:///v1/bi/admin/clients/DEF/ \
-H "CTN: " \
--cookie "LASID=;ATN=;RTN="
```
***
## What Gets Created
| Resource | ID Format | Purpose |
| ----------------- | -------------- | ---------------------------------------------------------------------- |
| Connection | `D2026A00XXX` | Snowflake data source credentials |
| Semantic Model | `SM2026A00XXX` | Client model inheriting from core (dimensions, measures, calculations) |
| Virtual Data Mart | `V2026A00XXX` | Bridge linking model to connection, with security bindings |
| Facade | `F2026A00XXX` | Dashboard with experiments and charts (if dashboard template provided) |
| Client Registry | MongoDB record | Tracks all resources for the client with status and audit info |