Environment variables and secrets in Supabase - Deep Dive

Overview - Environment variables and secrets

What is it?

Environment variables are special settings stored outside your code that tell your app how to behave. Secrets are sensitive pieces of information like passwords or keys that you keep hidden and safe. Together, they help your app connect to services securely without exposing sensitive data in the code. This keeps your app flexible and safe when moving between different places like your computer and the cloud.

Why it matters

Without environment variables and secrets, you would have to put sensitive information directly in your code. This is risky because anyone who sees your code could steal passwords or keys. Also, changing settings would mean changing code, which is slow and error-prone. Using environment variables and secrets makes your app safer and easier to manage, especially when working with cloud services like Supabase.

Where it fits

Before learning this, you should understand basic app development and how apps connect to databases or APIs. After this, you can learn about secure deployment, secret management tools, and advanced cloud security practices.

Mental Model

Core Idea

Environment variables and secrets are like a secret message board outside your app where you store important instructions and passwords safely, so your app can read them without exposing them in its code.

Think of it like...

Imagine your app is a chef in a kitchen. Environment variables are the recipe notes stuck on the fridge that tell the chef how to cook today, like which ingredients to use. Secrets are the secret family spices locked in a safe. The chef reads the notes and uses the spices without anyone else seeing the secret recipe.

┌─────────────────────────────┐
│       Environment Store      │
│ ┌───────────────┐           │
│ │ ENV VARS      │           │
│ │ - API_URL     │           │
│ │ - MODE        │           │
│ └───────────────┘           │
│ ┌───────────────┐           │
│ │ SECRETS       │           │
│ │ - DB_PASSWORD │           │
│ │ - API_KEY     │           │
│ └───────────────┘           │
└─────────────┬───────────────┘
              │
              ▼
       ┌─────────────┐
       │   Your App  │
       │ Reads vars  │
       │ and secrets │
       └─────────────┘

Build-Up - 7 Steps

1

Foundation

What are environment variables

Concept: Introduce environment variables as external settings for apps.

Environment variables are like labels outside your app that hold information your app needs to run. For example, instead of writing the database address inside your code, you put it in an environment variable called DATABASE_URL. Your app reads this label when it starts. This way, you can change the database without changing your code.

Result

Your app can connect to different databases or services just by changing environment variables, without touching the code.

Understanding environment variables helps you separate configuration from code, making apps more flexible and easier to manage.

2

Foundation

Understanding secrets in apps

Concept: Explain what secrets are and why they must be protected.

Secrets are sensitive pieces of information like passwords, API keys, or tokens. They let your app prove who it is to other services. If someone steals your secrets, they can pretend to be your app and cause harm. So, secrets must be stored safely and never put directly in your code or shared publicly.

Result

You learn to treat secrets carefully and keep them out of your code to protect your app and data.

Knowing what secrets are and why they matter is the first step to keeping your app secure.

3

Intermediate

How Supabase handles environment variables

🤔Before reading on: do you think Supabase stores environment variables inside your app code or separately? Commit to your answer.

Concept: Supabase stores environment variables outside your app code and provides a way to manage them securely.

In Supabase, you set environment variables in the project settings under 'API' or 'Settings'. These variables include your database URL, anon keys, and service role keys. Supabase injects these variables into your app environment when it runs, so your app can access them safely without hardcoding them.

Result

Your app running on Supabase can access environment variables securely, and you can update them without changing your app code.

Understanding Supabase's environment variable management helps you keep your app secure and flexible in the cloud.

4

Intermediate

Best practices for managing secrets

🤔Before reading on: do you think it's safe to share your API keys in public code repositories? Commit to your answer.

Concept: Learn how to keep secrets safe using environment variables and avoid common mistakes.

Never put secrets directly in your code or public repositories. Use environment variables or secret managers provided by your cloud platform. Rotate keys regularly and limit their permissions. In Supabase, use the service role key only on the server side, never in client code. Use anon keys for public access with limited rights.

Result

Your secrets stay safe, reducing the risk of leaks or unauthorized access.

Knowing how to manage secrets properly prevents security breaches and protects your users and data.

5

Advanced

Using environment variables in local development

🤔Before reading on: do you think local environment variables should be the same as production? Commit to your answer.

Concept: Learn how to use environment variables locally to mimic production safely.

When developing locally, create a .env file to store environment variables. This file is loaded by your app but never pushed to public repositories. Use different values than production to avoid accidental data leaks or changes. Tools like Supabase CLI can help manage local environment variables and secrets.

Result

You can develop and test your app safely without risking production secrets.

Understanding local environment variables helps you build and test apps securely before deploying.

6

Advanced

Automating secret updates in deployment

🤔Before reading on: do you think updating secrets requires manual changes in all environments? Commit to your answer.

Concept: Learn how to automate secret management during app deployment.

Use deployment pipelines or scripts to update environment variables and secrets automatically when you deploy your app. This reduces human error and keeps secrets consistent across environments. Supabase supports environment variable updates via its dashboard or API, which can be integrated into CI/CD pipelines.

Result

Your app always uses the latest secrets without manual intervention, improving security and reliability.

Automating secret updates reduces mistakes and keeps your app secure in production.

7

Expert

Hidden risks and advanced secret management

🤔Before reading on: do you think environment variables are always safe from leaks? Commit to your answer.

Concept: Explore subtle risks like environment variable leaks and advanced protection methods.

Environment variables can leak through logs, error messages, or if your app exposes them accidentally. Use secret managers that encrypt secrets at rest and in transit. Limit access to secrets using roles and policies. In Supabase, avoid exposing service role keys in client code. Use vaults or cloud secret managers for highly sensitive data.

Result

You understand that environment variables are not foolproof and learn how to protect secrets beyond basic usage.

Knowing the hidden risks of environment variables helps you design truly secure systems.

Under the Hood

Environment variables are stored by the operating system or cloud platform outside the app code. When the app starts, it reads these variables from its environment. Secrets are stored securely by the platform, often encrypted, and injected into the environment only when needed. Supabase manages these variables in its backend and injects them into your app's runtime environment, isolating secrets from the client side unless explicitly exposed.

Why designed this way?

Separating configuration and secrets from code allows apps to be portable and secure. Historically, hardcoding secrets led to leaks and inflexible apps. Environment variables became a standard because they are simple, supported everywhere, and keep secrets out of code repositories. Supabase builds on this by providing a managed way to store and inject these variables securely in cloud apps.

┌───────────────┐       ┌─────────────────────┐
│  Supabase     │       │  Your App Runtime   │
│  Secret Store │──────▶│  Environment Vars   │
│ (Encrypted)   │       │  & Secrets Loaded   │
└───────────────┘       └─────────┬───────────┘
                                      │
                                      ▼
                             ┌─────────────────┐
                             │  App Code Reads  │
                             │  Vars & Secrets  │
                             └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: do you think putting secrets in environment variables is always 100% safe? Commit to yes or no.

Common Belief: Environment variables are completely secure and cannot leak.

Reality: Environment variables can leak through logs, error messages, or if the app exposes them unintentionally.

Why it matters: Assuming environment variables are foolproof can lead to accidental secret exposure and security breaches.

Quick: do you think it's okay to commit environment variable files like .env to public repositories? Commit to yes or no.

Common Belief: It's fine to share .env files in code repositories for convenience.

Reality: Committing .env files with secrets exposes them publicly, risking theft and misuse.

Why it matters: This mistake is a common cause of data leaks and unauthorized access in real projects.

Quick: do you think all environment variables are secrets? Commit to yes or no.

Common Belief: All environment variables contain sensitive secrets.

Reality: Many environment variables are just configuration settings and not sensitive, like app mode or API URLs.

Why it matters: Confusing config with secrets can lead to overcomplicated secret management or ignoring real secrets.

Quick: do you think client-side code should use service role keys? Commit to yes or no.

Common Belief: It's okay to use powerful service role keys in client apps for convenience.

Reality: Service role keys have full access and must never be exposed to clients; use limited anon keys instead.

Why it matters: Exposing service role keys risks full database compromise and data loss.

Expert Zone

1

Environment variables can be overridden at different layers: OS, container, or cloud platform, which can cause unexpected behavior if not managed carefully.

2

Secrets should be rotated regularly and have limited permissions to minimize damage if leaked, a practice often overlooked in simple setups.

3

Supabase's separation of anon and service role keys enforces a security boundary that many beginners miss, leading to accidental privilege escalation.

When NOT to use

Environment variables are not suitable for very large or complex secret management needs. In such cases, use dedicated secret management tools like HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault that provide encryption, auditing, and fine-grained access control.

Production Patterns

In production, teams use CI/CD pipelines to inject environment variables and secrets securely during deployment. They separate secrets by environment (dev, staging, prod) and use role-based access to limit who can view or change secrets. Supabase projects often use anon keys in frontend apps and service role keys only in backend functions or serverless environments.

Connections

Configuration Management

Environment variables are a form of configuration management.

Understanding environment variables helps grasp how apps adapt to different environments without code changes, a core idea in configuration management.

Cryptography

Secrets rely on cryptography for secure storage and transmission.

Knowing how secrets are encrypted and decrypted deepens trust in secret management systems and highlights the importance of protecting keys.

Human Memory and Password Management

Managing secrets in apps is like managing passwords in daily life.

Just as people use password managers to keep secrets safe and avoid reuse, apps use secret managers and environment variables to protect sensitive data systematically.

Common Pitfalls

#1 Putting secrets directly in code files.

Wrong approach:

const DB_PASSWORD = 'mysecretpassword'; // hardcoded in code

Correct approach:

const DB_PASSWORD = process.env.DB_PASSWORD; // read from environment variable

Root cause:

Beginners often find it easier to put secrets in code but don't realize this exposes them to anyone who sees the code.

#2 Committing .env files with secrets to public repositories.

Wrong approach:

# .env file committed
DB_PASSWORD=mysecretpassword
API_KEY=abcdef12345

Correct approach:

# .env file added to .gitignore and not committed
# Secrets set in environment or secret manager

Root cause:

Lack of understanding that .env files contain sensitive data and should be kept private.

#3 Using service role keys in frontend code.

Wrong approach:

const supabase = createClient(SUPABASE_URL, SERVICE_ROLE_KEY); // exposed in client

Correct approach:

const supabase = createClient(SUPABASE_URL, ANON_KEY); // limited permissions for client

Root cause:

Confusing the roles of different keys and underestimating the risk of exposing powerful keys.

Key Takeaways

Environment variables separate configuration from code, making apps flexible and easier to manage.

Secrets are sensitive data that must be stored securely and never hardcoded or exposed publicly.

Supabase provides a secure way to manage environment variables and secrets, injecting them safely into your app environment.

Proper secret management includes using different keys for client and server, rotating keys, and avoiding leaks through logs or code.

Advanced secret management involves encryption, access control, and automation to keep your app secure in production.