--- title: "rayfin.yml reference" description: "The complete rayfin.yml schema, key by key — id, services.auth, services.data, services.storage, services.staticHosting, services.functions, and connectors." url: https://rayfin.ai/docs/reference/config/rayfin-yml markdown_url: https://rayfin.ai/docs/reference/config/rayfin-yml.md section: reference product: Rayfin sdk_version: 1.34.0 cli_version: 1.33.2 last_updated: 2026-08-29T23:37:34-07:00 source: reference/config/rayfin-yml.mdx --- # rayfin.yml reference > The complete rayfin.yml schema, key by key — id, services.auth, services.data, services.storage, services.staticHosting, services.functions, and connectors. `rayfin/rayfin.yml` is a project's committed configuration file: which services are enabled, the database dialect, static hosting settings, and Functions settings. The CLI reads it on every command and writes back to it during scaffolding, `rayfin init` reconfiguration, and (for `allowedRedirectUris` and connector entries) after a deploy. > [!WARNING] > Always declare `services.auth` and `services.data` explicitly, even as `enabled: false`. > The CLI reads those keys without guarding and does no defaulting — omitting either block > entirely causes a failure rather than falling back to a default. Also: if > `services.data.enabled` is `true`, omitting `dialect` causes a 400 at deploy time > (`Dialect is required when Data module is enabled`). ## Top-level keys [#top-level-keys] | Key | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | **Required.** Unique project identifier. Used as the Fabric item name when deploying. | | `name` | string | **Required.** Human-readable project name. | | `version` | string | **Required.** Project version string. | | `services` | object | **Required.** See below. | | `connectors` | list | Optional. External Fabric data sources. Each entry has its own `name` — see [Connector](/docs/reference/cli/connector). | | `frontend` | object | Deprecated. The frontend framework is now auto-detected from `vite.config.*` / `next.config.*` / `package.json` at runtime. Retained only for backward compatibility with older `rayfin.yml` files. | | `publishable_key` | string | Legacy. Some projects scaffolded by older CLI versions carry a top-level `publishable_key`. Current CLI versions manage the publishable key through `rayfin/.env` (`RAYFIN_PUBLIC_PUBLISHABLE_KEY`) instead — see [Environment variables](/docs/reference/config/environment-variables). | ## `services.auth` [#servicesauth] | Key | Type | Description | | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | **Required.** Turns the Auth service on or off. | | `fabric.enabled` | boolean | Fabric SSO (Entra ID). The only supported authentication method. | | `allowedRedirectUris` | string\[] | Origins allowed to receive auth redirects. `rayfin up` appends the live hosting URL here automatically after a static deploy. | | `expiryInMinutes` | number | Session token lifetime. | | `customClaims` | map | Additional claims to include in issued tokens. | | `scopes` | string\[] | Additional OAuth scopes. | | `refreshToken.lifetimeInDays` | number | Refresh token lifetime. | ## `services.data` [#servicesdata] | Key | Type | Description | | --------- | ------- | ------------------------------------------------------------------ | | `enabled` | boolean | **Required.** Turns the Data service (Data API Builder) on or off. | | `dialect` | `mssql` | **Required if `enabled` is `true`.** Fabric supports `mssql` only. | ## `services.storage` [#servicesstorage] | Key | Type | Description | | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `enabled` | boolean | Turns the Storage service (Azure Storage) on or off. Requires the `storage` feature flag to configure interactively — see [Environment variables](/docs/reference/config/environment-variables). | ## `services.staticHosting` [#servicesstatichosting] | Key | Type | Description | | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | Turns static hosting on or off. | | `folder` | string | **Required if `enabled` is `true`.** Build output directory to package and deploy, relative to the project root. | | `buildCommand` | string | Command to run before packaging (e.g. `npm run build:fabric`). | | `indexDocument` | string | Default document served for directory requests (e.g. `index.html`). | | `root` | string | Root directory of the frontend project, relative to the project root. Optional. | ## `services.functions` [#servicesfunctions] | Key | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `enabled` | boolean | Turns the Functions service on or off. `rayfin functions init` sets this to `true` automatically when scaffolding. | | `buildCommand` | string | Command to run before deploying Functions. Optional. | ## `services.connectors` [#servicesconnectors] | Key | Type | Description | | --------- | ------- | ------------------------------------------------------------------------------------------------- | | `enabled` | boolean | Registers the `rayfin connector` command group without needing `RAYFIN_FEATURE_FLAGS=connectors`. | Set this before adding the first connector: ```yaml title="rayfin/rayfin.yml" services: connectors: enabled: true ``` ## `connectors` [#connectors] `connectors:` is a top-level **list** of entries, not a map keyed by connector name. `rayfin connector add` writes this block and keeps it in the current list shape. See [Adding a connector](/docs/connectors/adding) and [Connector authentication](/docs/connectors/auth). | Field | Type | Required | Notes | | -------------------- | ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | Unique. Must match `/^[a-zA-Z0-9\-_]+$/` and be at most 256 characters. | | `type` | string | yes | One of `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `fabric-semanticmodel`, or `kusto`. | | `version` | string | Category B only | Positive integer string, for example `'1'`. Required for `fabric-semanticmodel` and `kusto`. | | `config.workspaceId` | string | yes | Fabric workspace ID. | | `config.itemId` | string | yes | Fabric item ID. | | `auth.type` | `delegated` \| `application` | yes | Lowercase. `application` is rejected on Category B types. | | `operations[].name` | string | no | Operation objects, not bare strings. Must be a subset of the type's allowed operations; defaults to all allowed operations. | ```yaml title="rayfin/rayfin.yml" connectors: - name: sales_warehouse type: fabric-warehouse config: workspaceId: 00000000-0000-0000-0000-000000000000 itemId: 11111111-1111-1111-1111-111111111111 auth: type: delegated operations: - name: read - name: create - name: update - name: delete - name: sales_model type: fabric-semanticmodel version: '1' config: workspaceId: 00000000-0000-0000-0000-000000000000 itemId: 22222222-2222-2222-2222-222222222222 auth: type: delegated operations: - name: executeQuery ``` For `kusto`, `queryServiceUri` and `databaseName` are never written into `rayfin.yml`. They live only in the generated `rayfin/connectors//schema.ts`. ## Complete annotated example [#complete-annotated-example] This is a real, deployed project's `rayfin.yml` (from a project scaffolded with the `todoapp` template): ```yaml title="rayfin/rayfin.yml" id: test1 name: test1 version: 1.0.0 services: auth: enabled: true fabric: enabled: true # Fabric SSO — the only supported auth method allowedRedirectUris: - http://localhost:5173 # local Vite dev server - https://clear-gale-6d8b0ba024-westus.webapp.rayfingwdev.com # appended by `rayfin up` after the first static deploy data: enabled: true dialect: mssql # required whenever data.enabled is true storage: enabled: false # declared explicitly even though unused — see the warning above staticHosting: enabled: true folder: dist # Vite's build output directory buildCommand: npm run build:fabric indexDocument: index.html functions: enabled: false publishable_key: pk-atYGKKCZi3uykRKndYqX # legacy — current CLI versions keep this in rayfin/.env instead ``` ## Environment variable interpolation [#environment-variable-interpolation] Any value in `rayfin.yml` can reference an environment variable with `${VAR}` or `${VAR:-default}`: ```yaml services: data: dialect: ${DB_DIALECT:-mssql} ``` See [Environment variable interpolation](/docs/reference/config/env-interpolation) for the full syntax, type coercion rules, and resolution priority. ```prompt title="Audit required service declarations" Read my project's rayfin/rayfin.yml and confirm that both services.auth and services.data are declared explicitly, even if disabled, and that services.data.dialect is set to mssql whenever services.data.enabled is true. Fix anything missing, then run `npx rayfin up --dry-run` to confirm the change is valid before deploying for real. ```