Secrets & Environment Variables
Manage API keys and environment variables for your Convex backend.
Click the Settings button in the builder toolbar to open the Settings sheet. It has three sections:
| Section | What it’s for |
|---|---|
| General | Project name and knowledge base |
| SEO & sharing | Set the site title, description, and favicon |
| Secrets | Environment variables for your Convex backend |
How do I add a secret?
Section titled “How do I add a secret?”- Click the Settings button in the builder toolbar
- Open the Secrets tab
- Enter a name (like
STRIPE_SECRET_KEY) and value - Click Add
How do I use secrets in my app?
Section titled “How do I use secrets in my app?”Secrets are synced to your app’s Convex backend. Reference them in Convex action/mutation/query code with process.env.SECRET_NAME. They are NOT available in your frontend code or as pod-level environment variables — this prevents secrets from leaking into the browser bundle.
The AI automatically uses your secrets when building features:
"Accept payments with Stripe"→ uses yourSTRIPE_SECRET_KEY"Send emails with Resend"→ uses yourRESEND_API_KEY"Add Google OAuth"→ uses yourGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET
Secrets are only accessible in your Convex backend functions (actions and mutations), not in frontend React code. The AI generates Convex functions that read them via process.env.
Can I view/edit a secret after creating it?
Section titled “Can I view/edit a secret after creating it?”Secret values are masked by default. You can toggle visibility to reveal values, update them, or delete and recreate them.
Can the AI see my secrets?
Section titled “Can the AI see my secrets?”The AI can see your secret names but not their values. This lets it reference the correct environment variable when building features without exposing sensitive data.
Sensitive Key Detection
Section titled “Sensitive Key Detection”Proyecta automatically detects common sensitive key patterns (API keys, tokens, passwords) and masks their values in the UI.
Site Metadata
Section titled “Site Metadata”The SEO & sharing section lets you set:
- Site title — appears in the browser tab and search results
- Site description — used for SEO meta descriptions
- Favicon — the icon shown in browser tabs
These settings are stored on your project and applied when you publish.
Knowledge Base
Section titled “Knowledge Base”The Knowledge Base section lets you add reference materials and context that the AI uses when building your app. Add brand guidelines, technical specifications, or any other documentation that helps the AI make better decisions.
Are secrets encrypted?
Secrets are stored in your project and synced to your Convex deployment. They never appear in your committed code.
Can I have different secrets for dev and production?
Today, secrets apply to both your development runtime and your published (production) Convex deployment. Per-environment secret management is planned for a future release.
What if I accidentally expose a secret?
Immediately delete the old secret, revoke the key with the third-party provider, and create a new one.
What’s the difference between secrets and connectors?
Secrets are raw environment variables you manage yourself. Connectors are managed integrations where Proyecta handles credential storage, authentication, token refresh, and audit logging for you. Use connectors when available (Stripe, Slack, Resend, ElevenLabs); use secrets for services that don’t have a connector yet.