mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 09:55:06 +03:00
Miranda Limonczenko
9a60894bfa
Production secrets sat after two non-procedure sections, so the reader setting up a key crossed reference material to get from the local steps to the production ones. Move it up to follow Local secrets, which runs all four procedure sections unbroken before the reference sections. Group "Where local values come from" and "Default secrets" under a Reference heading. Both answer "what are its parts?", so both are Structure under the style guide's information types, and Reference is the group the worked outline ends with. They demote from H2 to H3, which keeps them in the page TOC, since it is built from h2 and h3. No heading is renamed, so the anchors Studio deep-links into (#default-secrets, #using-the-cli) and the one the secrets-limit troubleshooting page uses (#accessing-environment-variables) are intact. Changing a heading's level preserves its slug. Glue the new shape needs: an outline of the three section groups at the top, a transition out of the troubleshooting section, and an opening line under Reference.
234 lines
9.8 KiB
Plaintext
234 lines
9.8 KiB
Plaintext
---
|
|
id: 'functions-secrets'
|
|
title: 'Environment variables'
|
|
description: 'Set, read, and deploy Edge Function secrets.'
|
|
subtitle: 'Store API keys and other secrets where your Edge Functions can read them.'
|
|
---
|
|
|
|
Local development and production load secrets differently, so set them in both.
|
|
|
|
- [Local secrets](#local-secrets) and [Production secrets](#production-secrets) have the steps for each environment.
|
|
- [Accessing environment variables](#accessing-environment-variables) shows how to read a secret from your function code. [When your function can't read a secret](#when-your-function-cant-read-a-secret) covers the local case where nothing arrives.
|
|
- [Reference](#reference) explains which file feeds which runtime, and lists the variables Supabase injects for you.
|
|
|
|
## Local secrets
|
|
|
|
Locally, Edge Functions read secrets from `supabase/functions/.env`. The local stack loads that file on `supabase start`.
|
|
|
|
1. Create `supabase/functions/.env` and add each secret with the value you want the function to read. A `.env.example` template isn't enough, because the runtime reads the values rather than the variable names.
|
|
|
|
```bash
|
|
# supabase/functions/.env
|
|
STRIPE_SECRET_KEY=sk_test_...
|
|
```
|
|
|
|
2. Add the file to your `.gitignore`, along with every other env file you create. A `.env` file committed to Git exposes every secret in it to anyone who can read the repository.
|
|
|
|
```bash
|
|
# .gitignore
|
|
supabase/functions/.env
|
|
.env.local
|
|
```
|
|
|
|
3. Create the function, then replace its contents to read the secret and report whether it arrived. Return the result of the check rather than the value, so the response never carries the secret.
|
|
|
|
```bash
|
|
supabase functions new hello-world
|
|
```
|
|
|
|
```ts
|
|
// supabase/functions/hello-world/index.ts
|
|
Deno.serve(() => {
|
|
const secretKey = Deno.env.get('STRIPE_SECRET_KEY')
|
|
return Response.json({ configured: Boolean(secretKey) })
|
|
})
|
|
```
|
|
|
|
4. Start the local stack.
|
|
|
|
```bash
|
|
supabase start
|
|
```
|
|
|
|
5. Call the function. When `configured` comes back `true`, the runtime handed the secret to your function.
|
|
|
|
```bash
|
|
curl -i --location --request POST 'http://127.0.0.1:54321/functions/v1/hello-world' \
|
|
--header 'apikey: <SUPABASE_PUBLISHABLE_KEY>'
|
|
```
|
|
|
|
Your function now reads the secret from your local environment.
|
|
|
|
---
|
|
|
|
## Production secrets
|
|
|
|
Set secrets for your production Edge Functions in the Supabase Dashboard or with the Supabase 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.
|
|
2. Enter the **Key** and **Value** for your secret, then click **Save**.
|
|
|
|
<Image
|
|
alt='The Edge Function Secrets page in the Supabase Dashboard. An Add new secrets card holds a Key field whose placeholder reads "e.g. CLIENT_KEY" and a Value field with a reveal toggle and a remove button, above an Add another button and a Save button.'
|
|
src={{
|
|
light: '/docs/img/edge-functions-secrets--light.jpg',
|
|
dark: '/docs/img/edge-functions-secrets.jpg',
|
|
}}
|
|
width={3757}
|
|
height={1525}
|
|
/>
|
|
|
|
You can paste multiple secrets at once.
|
|
|
|
### Using the CLI
|
|
|
|
1. Create a `.env` file with the secrets you want to deploy, and add it to your `.gitignore` before you commit.
|
|
|
|
```bash
|
|
# .env
|
|
STRIPE_SECRET_KEY=sk_live_...
|
|
```
|
|
|
|
2. Push every secret in the file to your remote project. The command also makes them visible in the Dashboard.
|
|
|
|
```bash
|
|
supabase secrets set --env-file .env
|
|
```
|
|
|
|
`supabase secrets set` also sets production secrets individually, without a `.env` file.
|
|
|
|
```bash
|
|
supabase secrets set STRIPE_SECRET_KEY=sk_live_...
|
|
```
|
|
|
|
List the secrets set on your remote project:
|
|
|
|
```bash
|
|
supabase secrets list
|
|
```
|
|
|
|
<Admonition type="note">
|
|
|
|
Your functions read a new secret immediately, so you don't need to redeploy.
|
|
|
|
</Admonition>
|
|
|
|
Your deployed functions can now read the secret.
|
|
|
|
---
|
|
|
|
## Accessing environment variables
|
|
|
|
Read an environment variable with `Deno.env.get`, passing the name of the variable.
|
|
|
|
```js
|
|
Deno.env.get('NAME_OF_SECRET')
|
|
```
|
|
|
|
### In an Edge Function
|
|
|
|
Inside an Edge Function, the Supabase keys are already in the environment. Read them and pass them to `createClient`:
|
|
|
|
```ts
|
|
import { createClient } from 'npm:@supabase/supabase-js@2'
|
|
|
|
const SUPABASE_PUBLISHABLE_KEYS = JSON.parse(Deno.env.get('SUPABASE_PUBLISHABLE_KEYS')!)
|
|
|
|
// For user-facing operations (respects Row Level Security)
|
|
const supabase = createClient(
|
|
Deno.env.get('SUPABASE_URL')!,
|
|
// To use a different API key, change 'default' to your preferred key name
|
|
SUPABASE_PUBLISHABLE_KEYS['default']
|
|
)
|
|
|
|
const SUPABASE_SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
|
|
// For admin operations (bypasses Row Level Security)
|
|
const supabaseAdmin = createClient(
|
|
Deno.env.get('SUPABASE_URL')!,
|
|
// To use a different API key, change 'default' to your preferred key name
|
|
SUPABASE_SECRET_KEYS['default']
|
|
)
|
|
```
|
|
|
|
### In a Deno script
|
|
|
|
A Deno script you run yourself, outside `supabase functions serve`, doesn't read `supabase/functions/.env`. Pass the file with `--env-file`, and grant the script access to environment variables 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
|
|
|
|
A variable that comes back empty usually means the value never reached the runtime.
|
|
|
|
Restart the stack, or serve the function with the file passed explicitly:
|
|
|
|
```bash
|
|
supabase functions serve hello-world --env-file supabase/functions/.env
|
|
```
|
|
|
|
If the value still doesn't arrive, confirm you edited the file your runtime reads.
|
|
|
|
---
|
|
|
|
## Reference
|
|
|
|
Look up which file feeds which runtime, and which variables Supabase injects for you.
|
|
|
|
### 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`, is read only when you pass it 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 also has to be in `supabase/functions/.env`, even when the root file already holds the same value.
|
|
|
|
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:
|
|
|
|
| Variable | Description |
|
|
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `SUPABASE_URL` | The API gateway for your Supabase project. |
|
|
| `SUPABASE_DB_URL` | The URL for your Postgres database. Use it to connect directly to your database. |
|
|
| `SUPABASE_PUBLISHABLE_KEYS` | The `publishable` keys JSON dictionary for your Supabase API. Safe to use in a browser when you have Row Level Security enabled. |
|
|
| `SUPABASE_SECRET_KEYS` | The `secret` keys JSON dictionary for your Supabase API. These keys bypass Row Level Security, so use them in Edge Functions and **never** in a browser. |
|
|
| `SUPABASE_JWKS` | The JSON Web Key Set used to verify user JWTs. Same value served at `https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json`. |
|
|
|
|
Legacy keys:
|
|
|
|
| Variable | Description |
|
|
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `SUPABASE_ANON_KEY` | The `anon` key for your Supabase API. Safe to use in a browser when you have Row Level Security enabled. |
|
|
| `SUPABASE_SERVICE_ROLE_KEY` | The `service_role` key for your Supabase API. This key bypasses Row Level Security, so use it in Edge Functions and **never** in a browser. |
|
|
|
|
In a hosted environment, functions also have access to these variables:
|
|
|
|
| Variable | Description |
|
|
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
| `SB_REGION` | The region the function was invoked in. |
|
|
| `SB_EXECUTION_ID` | A UUID for the function instance, or [isolate](/docs/guides/functions/architecture#4-execution-mechanics-fast-and-isolated). |
|
|
| `DENO_DEPLOYMENT_ID` | The version of the function code, formatted as `{project_ref}_{function_id}_{version}`. |
|