How to Secure API Keys in Retool

Log in as an Admin and go to Settings (gear icon top-right or your-retool.com/settings). Find 'Configuration Variables' in the Settings sidebar (may be labeled 'Environment Variables' in older Retool versions). This is where you define key-value pairs that are available across all apps in the organization. Keys are stored encrypted in Retool's backend.

Click '+ New variable'. Enter a name following SCREAMING_SNAKE_CASE convention (e.g., STRIPE_SECRET_KEY, OPENAI_API_KEY, SENDGRID_API_KEY). Enter the value — the actual API key. Most critically: toggle the 'Secret' checkbox ON. Secret variables are write-only after initial creation — their value is never displayed in the UI again, preventing shoulder-surfing and accidental exposure in screenshots.

1// Configuration variable naming conventions:
2// STRIPE_SECRET_KEY    → Payment API key
3// OPENAI_API_KEY       → LLM API key
4// SENDGRID_API_KEY     → Email API key
5// INTERNAL_API_TOKEN   → Internal service token
6// DB_ENCRYPTION_KEY    → For data encryption
7
8// Non-secret variables (safe to display in UI):
9// STRIPE_PUBLISHABLE_KEY  → Public key, OK to show
10// APP_VERSION             → Version string
11// SUPPORT_EMAIL           → Email address

In any SQL or REST query, reference configuration variables using the retoolContext.configVars object. The syntax is {{ retoolContext.configVars.VARIABLE_NAME }}. For REST API queries, use this in the header value, URL, or body fields. For JS Queries, access the same object without {{ }} delimiters.

1// REST API query headers (e.g., Stripe API call):
2// Header: Authorization
3// Value: Bearer {{ retoolContext.configVars.STRIPE_SECRET_KEY }}
4
5// REST API query URL with config var:
6// https://api.example.com/v1/endpoint?token={{ retoolContext.configVars.API_TOKEN }}
7
8// In a JS Query (no {{ }} needed):
9const apiKey = retoolContext.configVars.OPENAI_API_KEY;
10const response = await fetch('https://api.openai.com/v1/chat/completions', {
11  method: 'POST',
12  headers: {
13    'Authorization': `Bearer ${apiKey}`,
14    'Content-Type': 'application/json'
15  },
16  body: JSON.stringify({ model: 'gpt-4', messages: [...] })
17});
18// NOTE: This makes a direct frontend fetch. For server-side calls,
19// use a resource query instead (resource handles auth server-side)

The most secure option for API keys is to configure them in a Retool Resource connection (Settings → Resources). When you create a REST API or GraphQL resource, you enter the base URL and auth credentials (API key, OAuth tokens, etc.) in the resource configuration. These credentials are stored encrypted, never sent to the browser, and injected server-side into requests by Retool's backend. This is stronger than configuration variables because the key never reaches the client.

On Business and Enterprise plans, configuration variables can have different values per environment (staging vs production). Click on a configuration variable and set different values for each environment. This lets you use a test API key in staging and a live key in production — accessed via the same {{ retoolContext.configVars.STRIPE_SECRET_KEY }} reference, with Retool injecting the correct value based on the current environment.

1// Same variable name, different per-environment values:
2// STRIPE_SECRET_KEY:
3//   staging  → sk_test_xxxxxxxx
4//   production → sk_live_xxxxxxxx
5
6// Query reference stays the same across environments:
7// Header: Authorization
8// Value: Bearer {{ retoolContext.configVars.STRIPE_SECRET_KEY }}
9
10// Check current environment in app logic:
11// {{ retoolContext.environment }}
12// → 'staging' or 'production'

When rotating an API key, follow this process: create the new key with your API provider, go to Settings → Configuration Variables, find the variable, and click Edit to update its value. Apps that use the variable immediately start using the new key — no app changes or republishing required. If you use resource-level auth, edit the resource's credential settings instead.