Rayfin

Secrets in functions

Declare Rayfin secrets with the CLI, read them as typed ctx.Secrets properties, and supply local values through local.settings.json.

New in 1.36

Use function secrets for values that must stay server-side: API keys, connection strings, signing keys, and service tokens. Declare them with rayfin secret set, then read them in a function through ctx.Secrets.<NAME>.

Note

Functions are generally available in Rayfin 1.36 and are not available in every Fabric region or tenant.

Declare a secret before reading it

npx rayfin secret set THIRD_PARTY_API_KEY --describe="API key used by summarizeText"

The CLI stores the secret value on the deployed Fabric app and records only metadata in rayfin/rayfin.yml:

rayfin/rayfin.yml
secrets:
  - name: THIRD_PARTY_API_KEY
    description: API key used by summarizeText

The value is never written to rayfin.yml.

To declare several secrets at once, set them from a dotenv file with npx rayfin secret set --env-file <path>. Every name in the file is recorded in rayfin.yml the same way, without a description. Changed in 2.0 See Secrets.

Read the typed secret

rayfin/functions/src/function_app.ts
import {
  UserDataFunctions,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

export type AppSchema = Record<string, never>;

const udf = new UserDataFunctions();

udf.func(
  'readApiKeyStatus',
  async (ctx: RayfinContext<AppSchema>): Promise<{ configured: boolean }> => {
    const apiKey = ctx.Secrets.THIRD_PARTY_API_KEY;
    return { configured: apiKey.length > 0 };
  },
  [],
);

ctx.Secrets.THIRD_PARTY_API_KEY is typed as string. Reading a name that is not declared in rayfin.yml is a TypeScript error.

How secret typing works

rayfin secret set and rayfin secret delete regenerate secrets.generated.ts in the src/ folder of your functions package — services.functions.path in rayfin.yml, so rayfin/functions/src/secrets.generated.ts by default — and print its path when the file changes. rayfin secret set --env-file does the same for every name in the file. Changed in 2.0 Functions builds and typegen also ensure the file exists before compiling.

The generated file augments RayfinSecretRegistry from @microsoft/fabric-user-data-functions:

rayfin/functions/src/secrets.generated.ts
declare module '@microsoft/fabric-user-data-functions' {
  interface RayfinSecretRegistry {
    THIRD_PARTY_API_KEY: string;
  }
}

export {};

Do not import or edit secrets.generated.ts. It only needs to be included by the functions tsconfig.json.

Secret names are used verbatim. A name that is not a valid TypeScript identifier, such as 1PASSWORD_TOKEN, is quoted in the generated file so the project still compiles; read it with bracket notation, ctx.Secrets['1PASSWORD_TOKEN']. Changed in 2.0

Runtime resolution order

When a function reads ctx.Secrets.<NAME>, Rayfin resolves the value in this order:

  1. The secrets the service provides for the invocation.
  2. process.env[NAME], used mainly for local development.

If a declared secret has no value in either place, the runtime throws:

No value available for secret '<NAME>'. Ensure it is declared in rayfin.yml and set with 'rayfin secret set'.

A deployed function fetches its secrets on the first read and can cache the values for a few minutes, so a value you change with rayfin secret set can take a few minutes to reach it. A function that reads no secret never fetches them. Changed in 2.0

Use local secrets while debugging

When you run npx rayfin dev or npx rayfin dev functions apply, local functions do not receive the deployed secret bag. Put local-only values under Values in local.settings.json:

rayfin/functions/local.settings.json
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "THIRD_PARTY_API_KEY": "local-development-value"
  }
}

local.settings.json is git-ignored by the scaffold. The CLI merges its own required values into the file and preserves keys you add.

Migrate from ctx.getSecret()

ctx.getSecret(name) still works, returns string | undefined, and falls back to process.env, but it is deprecated in 1.36. Deprecated in 1.36

rayfin/functions/src/function_app.ts
const before = ctx.getSecret('THIRD_PARTY_API_KEY');
const after = ctx.Secrets.THIRD_PARTY_API_KEY;

Use ctx.getSecret() only for a value you intentionally do not model in rayfin.yml, and suppress the deprecation locally at that call site.

PromptMove a function secret to typed ctx.Secrets
In my Rayfin 2.0 project, update a function that reads a server-side secret. Declare the secret with `npx rayfin secret set <NAME> --describe="<what it is used for>"` if it is not already in rayfin/rayfin.yml. Replace string-based `ctx.getSecret('<NAME>')` reads with `ctx.Secrets.<NAME>`. Do not put the secret value in source code, chat, `RAYFIN_PUBLIC_*`, or frontend code. For local debugging, add a local-only value under `Values` in rayfin/functions/local.settings.json. Run a TypeScript build or `npx rayfin dev functions apply` long enough to confirm `secrets.generated.ts` and `types.ts` are valid. After rotating a value, allow a few minutes before expecting deployed functions to read it.
Something wrong on this page?Report an issueEdit this page

On this page