Secrets in functions

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>.

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:

secrets:
  - name: THIRD_PARTY_API_KEY
    description: API key used by summarizeText

The value is never written to rayfin.yml.

Read the typed secret

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 rayfin/functions/src/secrets.generated.ts. Functions builds and typegen also ensure the file exists before compiling.

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

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.

Runtime resolution order

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

1. The host-provided secret bag delivered with 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'.

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:

{
  "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

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.