# Get started with Secrets

Store a secret, let deployed apps read it, read it back yourself, and delete it again, in about ten minutes.

Replace _STRIPE_API_KEY_ with a name of your own, _5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e_ with the
id the create returns, and _1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d_ with the id of one of your KMS
keys.

## Prerequisites

- Permission for `secrets:CreateSecret`, `secrets:GrantSecret`, `secrets:GetSecretValue` and
  `secrets:DeleteSecret`. In the console, also `secrets:ListSecrets` to open **Secrets**; without
  it the page says "You do not have permission to list secrets." The panel's **Last read** needs
  `secrets:GetSecretAccessLog`; without it the section says "The access log needs
  secrets:GetSecretAccessLog."
- An enabled KMS key. A new organization has one, named `default`. For the CLI and the API, find
  its id with `dcloud kms keys list` (`kms:ListKeys`).

## Step 1: Create a secret

**Console**
1. Open **Secrets**, then choose **Create secret**.
2. For **Name**, enter STRIPE_API_KEY.
3. For **Value**, paste the value.
4. Leave **Environment** at **Default**, so every environment gets this value.
5. Choose **Create secret**.

The secret appears in the list, version `v1`. The console encrypts it under your default key unless
you choose another under **Key and rotation**.

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

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

The answer carries the secret's `id`, never its value.

## Step 2: Let deployed apps read it

A deployment reads a secret only while the `deploy` consumer holds a grant on it, and a workflow
only with an `actions` grant. Binding the secret to an app's variable grants `deploy` by itself;
this step grants it ahead of time, the way you would for any consumer.

**Console**
1. In the list, choose the secret. Its panel opens.
2. Under **Consumers**, on the `deploy` row, choose **Grant**.

**CLI**
```sh
dcloud secrets secrets grant 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e --consumer deploy
```

**API**
```http
POST /secrets/api/secrets/5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e/grants
{ "consumer": "deploy" }
```

An app that binds the secret on its **Environment** page now gets it at each rollout; see
[Set environment variables](/docs/deploy/guide/set-environment-variables).

## Step 3: Read the value back

**Console**
1. In the secret's panel, under **Value**, choose **Reveal value**.
2. The value arrives masked. Show it or copy it with the buttons beside it.

Closing the panel forgets the value.

**CLI**
```sh
dcloud secrets secrets get-value 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e
```

**API**
```http
GET /secrets/api/secrets/5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e/value
```

The read is written to the secret's access log with the version you got. The panel's **Last read**
shows it.

## Clean up

**Console**
1. In the secret's panel, under **Danger zone**, choose **Delete secret**.
2. Enter the secret's name, then choose **Delete secret**.

**CLI**
```sh
dcloud secrets secrets delete 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e
```

**API**
```http
DELETE /secrets/api/secrets/5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e
```

The secret, its versions, its grants and its access log are deleted.

## Next steps

- [Keep one secret per environment](environments.md)
- [Use a secret in a workflow](use-a-secret-in-a-workflow.md)
- [Connect 1Password](connect-1password.md)
