Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(functions): answer the recurring secrets questions from reader feedback (#50422)

Miranda Limonczenko36749659e649
diff --git a/apps/docs/content/guides/functions/secrets.mdx b/apps/docs/content/guides/functions/secrets.mdx
index 769e686fb5f..cab98061f52 100644
--- a/apps/docs/content/guides/functions/secrets.mdx
+++ b/apps/docs/content/guides/functions/secrets.mdx
@@ -59,13 +59,13 @@ Your function now reads the secret from your local environment.
## Accessing environment variables
-Access an environment variable with Deno's built-in handler, passing the name of the variable you want.
+Access an environment variable with the `Deno.env.get` method, passing the name of the variable you want.
```js
Deno.env.get('NAME_OF_SECRET')
```
-For example, in a function:
+### In an Edge Function
```ts
import { createClient } from 'npm:@supabase/supabase-js@2'
@@ -88,6 +88,20 @@ const supabaseAdmin = createClient(
)
```
+### In a Deno script
+
+A Deno script you run yourself, outside `supabase functions serve`, doesn't read `supabase/functions/.env`. Pass the file, and grant the script access to the environment with `--allow-env`:
+
+```bash
+deno run --allow-env --env-file=supabase/functions/.env script.ts
+```
+
+Or set the variable for a single command:
+
+```bash
+STRIPE_SECRET_KEY=sk_test_... deno run --allow-env script.ts
+```
+
---
## When your function can't read a secret
@@ -112,6 +126,10 @@ supabase functions serve --env-file .env.local
Set secrets for your production Edge Functions in the Dashboard or with the CLI.
+Creating or deleting a production secret requires the Owner or Administrator role. Developers can view secrets but not change them. See [Access control](/docs/guides/platform/access-control#edge-config-permissions) for the full matrix.
+
+A secret name can't start with `SUPABASE_`. That prefix is reserved for the variables Supabase injects, and both the Dashboard and the Management API reject it.
+
### Using the Dashboard
1. Open [Edge Function Secrets](/dashboard/project/_/functions/secrets) in the Dashboard.
@@ -166,6 +184,23 @@ Your deployed functions can now read the secret.
---
+## Where local values come from
+
+A project can hold more than one file that feeds local environment variables, and they aren't interchangeable:
+
+- `supabase/functions/.env` is the one your Edge Functions read, loaded when the stack starts.
+- A file you name yourself, such as `.env.local`, passed to `supabase functions serve` with `--env-file`.
+- A `.env` at the root of your project is the one `config.toml` reads, through its `env()` function. See [Using secrets inside config.toml](/docs/guides/local-development/managing-config#using-secrets-inside-configtoml). A variable your function needs has to be in `supabase/functions/.env` too, even when the same value is already in the root file.
+
+You can also set local values in `config.toml` itself, under `[edge_runtime.secrets]`:
+
+```toml
+[edge_runtime.secrets]
+STRIPE_SECRET_KEY = "env(STRIPE_SECRET_KEY)"
+```
+
+---
+
## Default secrets
Alongside the secrets you set yourself, Edge Functions have access to these by default: