> ## Documentation Index
> Fetch the complete documentation index at: https://hercules.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Store API keys and other sensitive values securely. Scope each secret to production, development, or both. Hercules uses them when building features.

Use Secrets to securely store sensitive information like passwords and API keys. Use Secrets for all third-party API keys.

<div className="screenshot purple">
  <img src="https://mintcdn.com/zeus-0f6dadbf/bCFvmNdn_n5AL1da/images/apps/secrets.png?fit=max&auto=format&n=bCFvmNdn_n5AL1da&q=85&s=47d70049eb8a32c9c7236ade78c51e90" alt="Secrets management" style={{ maxWidth: "450px" }} width="1546" height="1722" data-path="images/apps/secrets.png" />
</div>

### How do I add a secret?

1. Open **Advanced** → **Secrets** in the sidebar (scroll down to find the Advanced group)
2. Fill in the **Key** and **Value** fields:
   * **Key** is the variable name your code reads, written in capitals with underscores. Examples: `OPENAI_API_KEY`, `STRIPE_SECRET_KEY`, `TWILIO_API_KEY`.
   * **Value** is the secret itself, copied from the provider. Examples: `sk-...` for OpenAI, `sk_live_...` for Stripe.
3. Pick which environments should receive it: **Production**, **Development**, or both
4. Click **Save**

### How do I use secrets in my app?

Hercules automatically uses your secrets when building features:

* "Send emails with SendGrid" uses your `SENDGRID_API_KEY`
* "Send SMS with Twilio" uses your `TWILIO_API_KEY`

Secrets are referenced in code with `process.env.SECRET_NAME`.

### What are environments?

Each secret is scoped to one or more environments:

* **Production** is your live app.
* **Development** covers your development deployments.

A secret set for both environments is available everywhere. A secret set for only one environment is invisible to the other. See [Environments](/apps/environments) for how development deployments work.

### Can I mark a secret as sensitive?

Yes. Check **Sensitive** when adding a secret to encrypt and hide the value after saving. Sensitive values can't be revealed again. To change a sensitive secret, edit it and enter a new value (leave blank to keep the current one).

### Can Hercules AI see my secrets?

Hercules AI can see your **secret names** but not values. This lets it reference the correct secret when building features without exposing sensitive data.

### Additional FAQ

<AccordionGroup>
  <Accordion title="What are managed secrets?">
    Hercules includes some predefined secrets for internal functionality (Hercules API keys, auth/OIDC
    tokens). These are marked as managed and you can't edit or delete them.
  </Accordion>

  <Accordion title="Can I have different values for the same key per environment?">
    Yes. Add the same key twice, once scoped to Production and once scoped to Development, each with
    its own value.
  </Accordion>

  <Accordion title="What if I accidentally expose a secret?">
    Immediately delete the old secret (in Hercules and the third-party) and create a new one with the
    fresh key.
  </Accordion>

  <Accordion title="How are secrets stored?">
    Secrets are encrypted at rest and never appear in your code or logs.
  </Accordion>
</AccordionGroup>