---
title: "Handling Secrets Safely"
description: "Creating, viewing, and rotating secrets without leaking plaintext."
---

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

# Handling Secrets Safely

## Goal <a id="environment-secret-values" />

Create, view, and rotate secrets (like database passwords or API tokens), and make sure they never appear as plaintext in any UI, log, or diagnostic information.

## When to use this task

- Configuring a runtime variable that needs to stay confidential, for the first time.
- Rotating a secret periodically, or when you suspect one may have leaked.
- Sharing diagnostic information with a support contact or teammate, but needing to confirm first that it contains no plaintext secret.

## Prerequisites

- The target Resource already exists.
- The new secret value is ready (for example, a newly generated API token).

## Inputs and defaults

| Rule | Description |
| --- | --- |
| Runtime variables only | A build-time variable (one that ends up in the build artifact) can never be marked as a Secret |
| The value is never echoed back | After creating/rotating, the CLI, Web, and API all show a masked status only — never the plaintext |
| Passing the value through stdin is recommended | Avoids the plaintext showing up in process arguments or shell history |

## CLI steps

```bash
# Create a resource-level secret (pass the value through stdin so it never appears in process args)
appaloft resource secrets create res_web APP_SECRET --stdin

# Rotate an existing secret
appaloft resource secrets rotate res_web APP_SECRET --stdin

# List secrets (shows masked status only)
appaloft resource secrets list res_web

# Delete a secret you no longer need
appaloft resource secrets delete res_web APP_SECRET
```

`--stdin` can't be combined with a positional value argument; Appaloft automatically strips a trailing newline, rejects empty input, and never prints the value to the terminal or logs.

When bulk-importing a pasted `.env` file, Appaloft automatically treats secret-shaped key names (like `DATABASE_URL`, `*_TOKEN`, `*_PASSWORD`, `*_PRIVATE_KEY`) as Secrets:

```bash
appaloft resource import-variables res_web --file .env.production
```

## Web steps

1. Open the Variables tab on the resource detail page.
2. Click **Add secret**, enter the key name and value.
3. After saving, the list only shows the masked status and last-updated time — never the plaintext.

## Expected output and status

After a successful create or rotate, the command only returns a confirmation (key name, scope, updated time) — never the value itself. This change only affects the snapshot used by the **next** deployment, and it never hot-updates a running instance.

## Verification

After rotating a secret, you must trigger a new deployment and then confirm through the health summary and logs that the app actually read the new value:

```bash
appaloft deployments redeploy res_web
appaloft resource logs res_web
```

## Rollback / recovery

Recommended rotation flow:

1. Set the new secret on the target resource.
2. Create a new deployment for the affected resources.
3. Confirm through the health summary and logs that the app read the new value.
4. Confirm the old secret is no longer being used.
5. Only then revoke the old secret from the external system (like a database or a third-party API console).

If the new deployment fails, you can roll back to a historical deployment that used the old secret (see [Rollback And Recovery](/docs/en/deliver/recovery/)) while keeping both the old and new secrets valid until you've confirmed the fix.

## Troubleshooting links

- [Generating A Safe Diagnostic Summary](/docs/en/troubleshoot/diagnostics/) — when copying diagnostic information for help, only copy key names, masked status, and error codes — never the `.env` file or the secret value itself.

## Related reference pages

- [Configuration Precedence](/docs/en/configuration/precedence/)
- [Managing SSH Credentials](/docs/en/servers/ssh-keys/)

Source: https://docs.appaloft.com/en/configuration/secrets/index.mdx