Secrets

Changed in 1.36

Rayfin stores application secrets on the deployed Fabric app so functions can read server-only values without shipping them to the browser.

Deploy before managing secrets

Secrets attach to an existing Fabric app deployment:

npx rayfin up

Without an active deployment, secret commands fail with:

❌ No remote endpoint configured
   Run 'rayfin up' first to deploy your item to Fabric.

Set one secret interactively

npx rayfin secret set OPENAI_KEY --describe="OpenAI API key for summarizeText"

The CLI prompts for the value with masked input. The value is sent to the deployed item and is not written to disk.

--describe must use equals syntax. This is rejected:

npx rayfin secret set OPENAI_KEY --describe "OpenAI API key"

The exact error is:

❌ --describe requires the = syntax: --describe="My description"
   Use '--describe="My description"' instead of '--describe "My description"'.

Descriptions are stored as secret metadata in rayfin/rayfin.yml:

secrets:
  - name: OPENAI_KEY
    description: OpenAI API key for summarizeText

Set a secret from stdin

Use --stdin for scripts and CI jobs that can supply the value securely:

printf '%s' "$OPENAI_KEY" | npx rayfin secret set OPENAI_KEY --stdin

If stdin is empty, the CLI fails with:

No secret value was provided on stdin.

Bulk-set secrets from a dotenv file

npx rayfin secret set --env-file rayfin/.env.secrets

OPENAI_KEY=sk-local-authoring-value
DATABASE_PASSWORD='quoted values are unwrapped'

Blank lines and # comments are ignored. Keys are used verbatim as secret names. Do not commit .env.secrets.

Invalid combinations fail before any upload:

Rotate a secret

Run secret set again with the same name. The new value replaces the old value, and functions read the new value on later invocations.

npx rayfin secret set OPENAI_KEY --describe="OpenAI API key for summarizeText"

List secrets

npx rayfin secret list

The command returns names and timestamps only. Values are never returned.

Use JSON output for scripts:

npx rayfin --json secret list

Delete a secret

npx rayfin secret delete OPENAI_KEY
npx rayfin secret delete OPENAI_KEY --yes

Deleting a secret removes its metadata from rayfin.yml and regenerates the typed secrets file so stale ctx.Secrets.OPENAI_KEY references stop compiling.

If the secret is not found, the CLI reports:

❌ Secret "OPENAI_KEY" was not found. It may already be deleted, or secret management may not be enabled for this item.
   Run 'rayfin secret list' to see existing secrets.

Read secrets from functions

Functions read declared secrets through ctx.Secrets:

import {
  UserDataFunctions,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

export type AppSchema = Record<string, never>;

const udf = new UserDataFunctions();

udf.func(
  'hasOpenAiKey',
  async (ctx: RayfinContext<AppSchema>): Promise<boolean> => {
    return ctx.Secrets.OPENAI_KEY.length > 0;
  },
  [],
);

See Secrets in functions for the generated secrets.generated.ts model and local development fallback.

Troubleshooting

The command refuses to prompt

Symptom: rayfin secret set <NAME> exits instead of asking for a value.

Cause: stdin is not a TTY or CI=true is set.

Fix: run it from an interactive terminal, or pipe the value with --stdin.

Authentication failed

Symptom: the command reports that it could not acquire an authentication token.

Cause: you are not signed in, your cached sign-in expired, or the machine cannot use the OS keychain.

Fix: run npx rayfin login. In containers or restricted environments, add --encryption-fallback-enabled if login reports a keychain error.

Permission denied

Symptom: setting, listing, or deleting a secret fails with a permission error.

Cause: the signed-in account does not have access to the target Fabric workspace or app item.

Fix: run npx rayfin login again and choose an account with workspace access. Confirm the active deployment with npx rayfin up status.

A function cannot read a declared secret

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

Cause: the name exists in rayfin.yml, but no deployed secret value or local process.env value is available.

Fix: run npx rayfin secret set <NAME> for deployed functions, or add a local-only value under Values in rayfin/functions/local.settings.json while debugging locally.