# What is Secrets?

Secrets keeps passwords, tokens and keys encrypted under one of your KMS keys and hands them to your apps and workflows by name, never in your code.

A secret is a named value, such as `STRIPE_API_KEY`, encrypted at rest under a customer managed key
(CMK) from KMS. No list or describe call ever returns a value: reading one is its own permission,
`secrets:GetSecretValue`, and every time a value is handed out, the read is written to the secret's access log. You find
it under **Secrets** in the Deutsche Cloud Console, with **Environments** and **Sources** beside it.

## When to use it

- An app deployed with Deutsche Cloud needs a database password or an API token as an environment
  variable, and you do not want it in the image, the repository or the build log.
- A workflow job needs a token, and only the workflows of one repository should get it.
- You keep secrets in 1Password or HashiCorp Vault / OpenBao already and want the platform to follow
  them instead of holding a second copy you have to update by hand.
- You run the same app in development, staging and production with a different value in each.

## Concepts

| Term                | Meaning                                                                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Secret**          | A named value encrypted under one CMK. The name is `UPPER_SNAKE_CASE`, starts with a letter and is unique per environment.                                      |
| **Version**         | One stored value of a secret. One version is active; the others are retired and can be made active again.                                                       |
| **Default**         | A secret that belongs to no environment. Every environment that has no secret of that name of its own gets the Default one.                                     |
| **Environment**     | Development, Staging, Production and any you add, in promotion order. A secret in an environment overrides the Default of the same name there.                  |
| **Consumer**        | A part of the platform that reads values on your behalf: `actions` (workflow jobs), `deploy` (app deployments), `compute`, `registry`, `cli`, `code`.           |
| **Grant**           | Permission for one consumer to read one secret, for `actions` optionally for one repository only, optionally until a date.                                      |
| **Group**           | Where a secret is filed, such as `dialog/auth`: up to three lower-case segments. A label for finding things; it grants nothing.                                 |
| **Source**          | A connected 1Password service account, or a HashiCorp Vault / OpenBao server. Its credential is stored as a secret of its own.                                  |
| **Synced secret**   | A secret whose value comes from a source reference such as `op://Production/Postgres/password`. The platform writes its versions; you do not rotate it by hand. |
| **Rotation policy** | A number of days that gives a secret a due date. Nothing changes the value for you.                                                                             |
| **Access log**      | Who or what read a secret's value, which version, and when.                                                                                                     |

More in [Secrets and versions](secrets-and-versions.md), [Environments](environments.md) and
[Keys and encryption](keys-and-encryption.md).

## Pricing

Secrets, environments and sources are not charged. The KMS key a secret is encrypted under is a KMS
resource.

## Interfaces

- The Deutsche Cloud Console, under **Secrets**: **Secrets**, **Environments** and **Sources**.
- The CLI: `dcloud secrets …`; see the _CLI Command Reference_.
- The HTTP API under `/secrets/api`; see the _API Reference_.
- Terraform: `dcloud_secret`, `dcloud_secret_grant`, `dcloud_secrets_environment` and
  `dcloud_secrets_source`.

## Next steps

- [Get started with Secrets](getting-started.md)
- [Create a secret](create-a-secret.md)
- [Grant a consumer access to a secret](grant-a-consumer.md)
