# Create a secret

Store a value as a secret, encrypted under one of your KMS keys, as the Default or for one environment.

Replace _STRIPE_API_KEY_ with the name apps and workflows will look the value up by, and
_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d_ with the id of an enabled KMS key.

## Prerequisites

- Permission for `secrets:CreateSecret`. In the console, also `secrets:ListSecrets` to open
  **Secrets**; without it the page says "You do not have permission to list secrets."
- An enabled `encrypt_decrypt` KMS key. Without one, the console's **Create secret** offers
  **Create an encryption key** (`kms:CreateKey`) and brings you back to the form.
- To create it in an environment, the environment's id (see
  [Manage environments](manage-environments.md)). In the console, the **Environment** picker lists
  the environments only with `secrets:ListSecretEnvironments`; without it, it offers **Default**
  only.
- A free unit of the secrets quota; see [Quotas](quotas.md).

## Create the secret

**Console**
1. Open **Secrets**, then choose **Create secret**.
2. For **Name**, enter STRIPE_API_KEY.
3. For **Value**, paste the value.
4. (Optional) For **Group**, choose or enter a group such as `payments`.
5. For **Environment**, keep **Default** for every environment, or choose one environment to
   override the Default there.
6. (Optional) For **Description**, enter what the value is for.
7. (Optional) Under **Key and rotation**, choose another **Encryption key**, or enter a number of
   days (1 to 3650) for **Remind me to rotate every (days)**. For **Scope**, choosing **Project**
   or **Resource** adds a required field of that name: enter the project or the resource name it
   is filed under.
8. (Optional) Under **Tags**, add tags. A tag your organization requires must be set before the
   form can be sent.
9. Choose **Create secret**.

The secret appears in the list as `v1`.

**CLI**
```sh
dcloud secrets secrets create --name STRIPE_API_KEY \
  --key-id 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d --value 'sk_test_EXAMPLE' --group payments
```

Add `--environment-id` for one environment, `--rotation-interval-days` for a due date.

**API**
```http
POST /secrets/api/secrets
{ "name": "STRIPE_API_KEY", "keyId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "value": "sk_test_EXAMPLE", "group": "payments" }
```

**Terraform**
```hcl
resource "dcloud_secret" "stripe" {
  name   = "STRIPE_API_KEY"
  key_id = "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  value  = var.stripe_api_key
  group  = "payments"
}
```

A changed `value` is a rotation, not a new secret. The value is never read back.

To create a secret whose value comes from 1Password or Vault, see
[Sync a secret from a source](sync-a-secret-from-a-source.md).

## Result

The answer is `201` with the secret, never its value. The value is version 1. No consumer may read
it yet; see [Grant a consumer access to a secret](grant-a-consumer.md).

A name that already exists in another environment keeps that name's group, whatever group you send.

## Refusals

- `409` "A shared secret named STRIPE_API_KEY already exists", or "STRIPE_API_KEY already exists in
  that environment".
- `404` "Environment not found"; `404` "Key not found".
- `409` "Key is not enabled"; `400` "Key must be an encrypt_decrypt key".
- `400` "Give either a value or a reference, not both", when both or neither are sent.
- `409` when the secrets quota is full.

## Related

- [Secrets and versions](secrets-and-versions.md)
- [Environments](environments.md)
- `secrets.secrets.create` · `dcloud secrets secrets create` · `dcloud_secret`
