Environment variables

Environment variables hold values that change by environment or must stay outside source code. Keep database credentials, auth secrets, provider tokens, and server-side Apso API keys outside the repository.

Local development

Use the generated project’s .env file for local service configuration:

DATABASE_TYPE=pglite
DATABASE_SYNC=true
APP_PORT=3100
BETTER_AUTH_SECRET=replace-with-a-long-random-value
STRIPE_SECRET_KEY=replace-with-a-test-key

Add .env to .gitignore. Commit an .env.example with names and harmless sample values so another developer knows what the service requires.

DATABASE_TYPE=pglite
DATABASE_SYNC=true
APP_PORT=3100
BETTER_AUTH_SECRET=
STRIPE_SECRET_KEY=

Hosted services

For a deployed hosted service:

1. Open the service in Apso Cloud .
2. Select Environment.
3. Click Add Variable.
4. Enter an uppercase key, its value, and whether the value is secret.
5. Save the variable.
6. Click Apply Changes to synchronize pending changes to the running service.

Environment changes also apply during a later deployment. Editing or deleting a variable creates another pending change until it is applied.

Variable classes

Access values in code

TypeScript

const stripeSecretKey = process.env.STRIPE_SECRET_KEY;
 
if (!stripeSecretKey) {
  throw new Error('STRIPE_SECRET_KEY is required');
}

Python

import os
 
stripe_secret_key = os.environ["STRIPE_SECRET_KEY"]

Go

stripeSecretKey := os.Getenv("STRIPE_SECRET_KEY")
if stripeSecretKey == "" {
    log.Fatal("STRIPE_SECRET_KEY is required")
}

Frontend boundaries

An Apso service API key is a server credential. Store it in a Next.js server environment and use it from Server Components, Server Actions, or route handlers. Do not place it in NEXT_PUBLIC_*, Vite VITE_*, React Native application code, or Flutter assets.

For browser and mobile clients, use a BFF or a user-scoped authentication token with the generated REST API.

Change workflow

1. Add the variable name to .env.example.
2. Configure a development value locally.
3. Read it from an extension or framework configuration module.
4. Add the hosted value in the Environment view.
5. Apply the pending change or deploy the service.
6. Exercise the affected endpoint and inspect logs without printing the secret.

Rotation

For a provider credential or auth secret:

1. Create the replacement at the provider.
2. Update the local or hosted value.
3. Apply the hosted change.
4. Verify the dependent workflow.
5. Revoke the old credential at the provider.