# Secrets and environment variables

Two kinds of values stay out of your code: **secrets** (passwords and <Term id="api-key">API keys</Term>) and **environment variables** (plain settings such as a public URL). Kept in the <Term id="project">project</Term>, a key never lands in your repository or an AI chat, and you change a value without changing code.

<Callout type="info" title="How secrets are protected">
Secrets are encrypted with a managed key service. Once saved, a value is hidden: nobody can read it back in the app or API, but your apps can still use it.
</Callout>

## Before you start [#before-you-start]

- Adding and changing them needs the **Owner** or **Admin** <Term id="roles">role</Term> on the project.
- The app asks you to confirm it is you first: select **Verify to view**, then **Continue** on "Verify it's you".

## Where to find them [#where-to-find-them]

- **Keys** in the sidebar, under **Ship**, covers every project. Pick one; the page says whether you can change or only view.
- In a project, open **Settings** and go to **Keys**.

## Secret or variable? [#secret-or-variable]

| Use a | For | After saving |
| --- | --- | --- |
| Secret | Passwords, tokens and API keys. | Hidden. You can replace it, turn it off or delete it, never read it. |
| Variable | Plain settings your apps can read. | Visible to people who can open the Keys section. |

## Add a secret [#add-a-secret]

<ForEveryone>
<Steps>
<Step>
### Open Secrets [#open-secrets]
In the project's **Keys** section, select **Verify to view** if asked, then go to **Secrets** and open **Add a secret**.
</Step>
<Step>
### Name it [#name-it]
Type a **Name**, for example `GITHUB_TOKEN`.
</Step>
<Step>
### Choose how it is used [#choose-how-it-is-used]
Under **How it is used**, choose one:
- **Added to requests to one website**: type the **Website** (for example `api.github.com`). Klarety adds the secret to every request there, so your code never holds the value. Optionally set the **Header** (for example `Authorization`) and a **Prefix** (for example `Bearer `).
- **A variable in your deployed apps**: your deployed app reads it as an environment variable of this name.
</Step>
<Step>
### Paste the value and choose where it reaches [#paste-the-value-and-choose-where-it-reaches]
Paste the **Value**. Under **Reaches**, choose **Studio**, **Preview** or **Production**.
</Step>
<Step>
### Save [#save]
Select **Add secret**.
</Step>
</Steps>

<Screenshot src="/docs/_media/dashboard-environment-keys-for-project.png" alt="The Add a secret form" />
</ForEveryone>

<ForDevelopers>
Secrets are write-only through the SDK too: `projects.secrets` returns names, hosts, versions and last use, never a value.

```python title="secrets.py"
from klarety import Nexus

nx = Nexus.connect()
project_id = "YOUR_PROJECT_ID"

nx.projects.set_secret(
    project_id,
    "GITHUB_TOKEN",
    "ghp_your_token",
    host="api.github.com",
    use="host",
    environments=["studio", "production"],
)

nx.projects.set_secret(project_id, "STRIPE_KEY", "sk_live_your_key", use="env")

for secret in nx.projects.secrets(project_id)["secrets"]:
    print(secret["name"], secret["host"], secret["version"])

nx.projects.disable_secret(project_id, "STRIPE_KEY")
nx.projects.delete_secret(project_id, "STRIPE_KEY")
```

`use="host"` adds the secret to requests to `host`, with `inject_header` (default `Authorization`) and `inject_prefix` (default `Bearer `). `use="env"` sets it as a variable named after the secret. `environments` takes `studio`, `preview` and `production`. To move a dotenv file in, `nx.projects.import_secrets(project_id, entries, host=...)` adds one secret per key.
</ForDevelopers>

## Change or remove a secret [#change-or-remove-a-secret]

Each secret shows where it reaches, its version and its last use.

- **Replace**: overwrites the value for good. The new one is used from the next request.
- **Turn it off**: pauses the secret without deleting it.
- **Delete**: it stops being sent at once and cannot be recovered.

## Add a variable [#add-a-variable]

<ForEveryone>
<Steps>
<Step>
### Open Environment [#open-environment]
In the project's **Keys** section, go to **Environment** and select **Add variable**.
</Step>
<Step>
### Fill it in [#fill-it-in]
Type the name and **Value**, and choose where it **Reaches** (Studio, Preview or Production). Mark it **Build** if your app needs it at build time, or **Public** if it is meant to be seen, for example in a web page.
</Step>
<Step>
### Save [#save-1]
Select **Save**. If you removed or renamed a variable, the app asks you to confirm first.
</Step>
</Steps>
</ForEveryone>

<Screenshot src="/docs/_media/dashboard-environment-keys-for-project.png" alt="The Environment section of a project's Keys with the Add variable form" />

<ForDevelopers>
`set_env` replaces the whole set, and only over the version you read, so two people never silently overwrite each other. A stale `version` gets a 409 conflict.

```python title="environment.py"
from klarety import Nexus

nx = Nexus.connect()
project_id = "YOUR_PROJECT_ID"

current = nx.projects.env(project_id)
entries = {**current["entries"], "APP_TITLE": "Sales dashboard"}

nx.projects.set_env(
    project_id,
    entries,
    version=current["version"],
    scopes={
        **current["scopes"],
        "APP_TITLE": {"environments": ["production", "preview"], "public": True},
    },
)
```
</ForDevelopers>

## When a change takes effect [#when-a-change-takes-effect]

- New <Term id="studio">Studios</Term> and new <Term id="deploy">deploys</Term> get a changed variable.
- Code that reads a removed or renamed variable stops finding it.
- A replaced secret is used from the next request. A deleted one stops at once.

<Callout type="warn" title="Redeploy after a change">
A running app keeps its old values until it is deployed again. See [Deploy an app](/docs/deploy/deploy-an-app).
</Callout>

## If something goes wrong [#if-something-goes-wrong]

<Accordions>
<Accordion title="App secrets and variables stay hidden">
You have not confirmed it is you recently. Select **Verify to view**.
</Accordion>
<Accordion title="You cannot add a secret">
Only the project's Owner and Admins can add or change secrets. Ask one of them.
</Accordion>
<Accordion title="You think a secret leaked">
Replace it with a new value at its source first, then **Replace** it here. If you think the project's own credentials leaked, use **Cut the project's access** in the Danger zone. See [Project settings](/docs/projects/settings).
</Accordion>
</Accordions>

## Next steps [#next-steps]

- [Project settings](/docs/projects/settings)
- [Deploy an app](/docs/deploy/deploy-an-app)
- [Security](/docs/get-started/security)