Manage Orga environment variables

Store and load your Orga API key securely across local development, staging, and production. This guide covers setting up .env files, loading variables in your code, and managing secrets in each environment.

Prerequisites

Access to the Orga dashboard to create API keys.
Secret storage mechanism (e.g., .env.local, Doppler, AWS Secrets Manager).
Node.js, React, or React Native projects that consume the values.

1. Identify required variables

You’ll need one environment variable to get started:

Variable	Required	Used by	Description
`ORGA_API_KEY`	Yes	Server SDK / backend proxy	Long-lived key that authenticates calls to Orga’s REST API. Prefixed with `sk_orga_ai_`.

Optional configuration like model, voice, or region can be set at runtime through the SDK—you typically don’t need to define them as environment variables unless you want global defaults across all sessions.

2. Create local `.env` files

For local development, create a .env.local file (Next.js) or .env file (Node/Express) in your project root. Never commit these files to version control.

.env.local


ORGA_API_KEY=sk_orga_ai_******************************

Important: Always add .env* files to your .gitignore. In React Native or Expo apps, keep your API key on the backend only—mobile clients should fetch credentials through your proxy endpoint, never bundle the key directly in the app.

3. Load variables in code

Initialize the Node SDK with your API key from the environment:

server.ts


import { OrgaAI } from '@orga-ai/node';
 
export const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  debug: process.env.NODE_ENV !== 'production',
});

Validate that the required variable is present before your app starts. This prevents runtime errors and makes failures obvious:


if (!process.env.ORGA_API_KEY) {
  throw new Error('Missing ORGA_API_KEY. Add it to your environment variables.');
}

4. Configure staging and production

Store your API keys securely in each environment using your platform’s secret management system:

Environment	Where to store	Tips
Local dev	`.env.local`, `direnv`, or VS Code secrets	Add `.env*` to `.gitignore`.
Staging	Platform secrets (Vercel, Render, Fly.io)	Create separate API keys for staging to isolate test usage.
Production	Secret manager (AWS Secrets Manager, GCP Secret Manager, Doppler)	Rotate keys periodically and restrict access to CI/CD roles.

Make sure your team knows where to find and update these secrets. Document the process in your internal docs or README.

5. Rotate keys safely

When you need to rotate your API key, follow this process to avoid downtime:

Create a new key in the Orga dashboard .
Update the secret in staging first, redeploy, and verify everything works.
Once staging looks good, update production secrets and redeploy.
Monitor logs to confirm traffic is flowing correctly, then delete the old key from the dashboard.

Troubleshooting

If you run into issues, here are common problems and solutions:

401 Unauthorized – Your API key is missing or malformed. Double-check that the environment variable is set correctly on your server and that it’s loading before the SDK initializes.
Build fails or TypeScript errors – Your bundler or TypeScript can’t find process.env keys. Add type declarations in an env.d.ts file or use your framework’s typed environment variable helpers.
Mobile app exposes the key – Never bundle ORGA_API_KEY in Expo or React Native code. Mobile clients should always fetch credentials through your backend proxy at /api/orga-client-secrets.

Once your environment variables are set up across all environments, you’re ready to build a secure backend proxy that issues ephemeral tokens to your clients.