# Store Passwords and API Keys Securely

:::lead
Secrets are encrypted values used to securely store sensitive information such as passwords, API keys, access tokens, and other credentials. Like Variables, they can be referenced throughout your Test Cases and Flows without exposing their actual values.
:::

:::callout{title="When should I use a Secret?"}
Use a Secret whenever the value is sensitive and shouldn't be visible to other users. For non-sensitive values such as URLs, usernames, or product IDs, use [Variables](/docs/data/variables) instead.
:::

## Common use cases

Secrets are commonly used for:

- Passwords
- API keys
- Access tokens
- Client secrets
- Database credentials
- Authentication tokens

## Creating a Secret

To create a Secret:

1. Open **Data Config** from the sidebar.
2. Select the **Secrets** tab.
3. Click **New Secret**.
4. Enter a unique name.
5. Enter the secret value.
6. Choose whether the Secret should be available globally or only for specific [Environments](/docs/environments/overview).
7. Save the Secret.

![Create Secret](/images/data/secrets/create-secret.png)

## Using Secrets

Secrets are referenced exactly like Variables using double curly braces.

```text
{{stripeApiKey}}
```

Most supported fields include a **Select from Variable or Secret** button, allowing you to insert Secrets without typing their names manually.

![Using Secrets](/images/data/secrets/using-secret.png)

## Secret scope

Secrets support the same scoping options as Variables.

### Global Secrets

Global Secrets are available throughout the entire project.

Examples include:

- Shared API keys
- Common authentication tokens
- Company-wide credentials

### Environment-specific Secrets

Environment-specific Secrets allow different environments to use different credentials while keeping the same Secret name.

For example:

| Environment | `stripeApiKey` |
| --- | --- |
| Development | Development API key |
| Staging | Staging API key |
| Production | Production API key |

This allows the same Test Case to run against different environments without modification.

## Updating Secrets

Unlike Variables, Secret values are **write-only**: TestOwl never shows a saved value again.

To change a Secret, edit it and enter a **New Value** to replace the old one. You can also change its name and scope. Any Test Case or Flow that references the Secret by name picks up the new value automatically.

:::info{title="Secret values are never displayed"}
After a Secret has been created, its value is never shown again in the TestOwl interface. If you need to verify the current value, check your organisation's password manager or other secure source of truth.
:::

## Deleting Secrets

Deleting a Secret moves it to the [Recycle Bin](/docs/workspace/recycle-bin) instead of permanently removing it.

Secrets remain in the Recycle Bin for **15 days** and can be restored during that time, after which they are permanently deleted.

:::warning{title="Before deleting a Secret"}
Before deleting a Secret, make sure it isn't referenced by any Test Cases or Flows. Removing a Secret may cause those tests to fail until the reference is updated.
:::

## Security

TestOwl encrypts every Secret before storing it. Secret values are never displayed in the user interface after creation and are only accessed during test execution when required.

## Best practices

- Store all passwords, API keys, and tokens as Secrets.
- Never store sensitive values in Variables.
- Use descriptive names such as `stripeApiKey` or `adminPassword`.
- Use Environment-specific Secrets when credentials differ between environments.
- Delete unused Secrets regularly to keep your project organised.

## Next steps

::::cardgrid
:::card{title="Variables" href="/docs/data/variables"}
Store reusable, non-sensitive values.
:::

:::card{title="Environments" href="/docs/environments/overview"}
Configure environment-specific Variables and Secrets.
:::

:::card{title="Step Editor" href="/docs/building-tests/the-editor"}
Learn how to use Variables and Secrets in your test steps.
:::
::::