# File secrets in groups

Move secrets into groups such as dialog/auth, one at a time or many at once, and change a secret's description and rotation interval.

A group is up to three segments separated by `/`, each lower-case letters, digits and hyphens (up
to 40 characters each, 122 in all), such as `dialog/auth`. `null` is Ungrouped. A group is a label
for finding things: no permission and no lookup reads it.

A group belongs to the secret's **name**: moving a secret moves the secret of that name in every
environment, and a secret created under a name that exists elsewhere joins that name's group.

Replace _5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e_ with the secret's id.

## Prerequisites

- Permission for `secrets:UpdateSecret` on the secret. To change its group, on every environment's
  secret of the name. In the console, also `secrets:ListSecrets` to open **Secrets**; without it
  the page says "You do not have permission to list secrets."
- To edit one secret's details: not a secret managed by Error Tracking (refused with `409`; the
  console shows no **Edit details** for it). Moving many at once does not refuse one.

## Change one secret's group and details

**Console**
1. Open **Secrets** and choose the secret.
2. In its panel, choose **Edit details**.
3. For **Group**, choose or enter the group, or choose **Ungrouped**.
4. (Optional) Change **Description** or **Rotate every (days)**. Empty means no rotation policy.
5. Choose **Save**.

**CLI**
```sh
dcloud secrets secrets update 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e --group dialog/auth \
  --description 'OAuth client of the auth service'
```

**API**
```http
PATCH /secrets/api/secrets/5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e
{ "group": "dialog/auth", "description": "OAuth client of the auth service" }
```

**Terraform**
Set `group`, `description` or `rotation_interval_days` on the `dcloud_secret`. They change in
place.

A changed rotation interval sets the due date that many days from now. The description and the
interval change this secret only; the group changes every environment's secret of the name. If one
of those may not be updated, the answer is `403` "Forbidden: needs secrets:UpdateSecret on every
environment's STRIPE_API_KEY" (with the secret's name), and nothing changes.

## Move many secrets at once

**Console**
1. Open **Secrets** and select the secrets' check boxes.
2. Choose **Move to group**.
3. For **Group**, choose or enter the group, or choose **Ungrouped**.
4. Choose **Move**.

A banner says how many were done and lists each refusal.

**CLI**
```sh
dcloud secrets secrets bulk-move --ids 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e --group dialog/auth
```

**API**
```http
POST /secrets/api/secrets/bulk/move
{ "ids": ["5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e"], "group": "dialog/auth" }
```

**Terraform:** not available. Set `group` on each `dcloud_secret`.

At most 500 ids per call. The answer is `{ results, succeeded, failed }`, one result per id; it is
not atomic. A name with one environment's secret refused does not move at all.

## See the groups

In the console the groups are the tree beside the list (a picker above the list on a narrow
screen); choosing one shows it and every group below it. `GET /secrets/api/groups` (or
`dcloud secrets groups list`) needs `secrets:ListSecrets` and returns the tree with how many
secrets each group holds, counting only secrets you may describe (`secrets:GetSecret`).

## Where the platform files secrets

The platform files a secret once, when it creates it; after that the group is yours to change.

| Created from                                     | Group                                                                                                                      |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| a 1Password reference `op://<vault>/<item>/…`    | `<vault>/<item>`, with environment words removed from the vault: `op://Dialog Prod/auth-service/…` → `dialog/auth-service` |
| a Vault reference `vault://<mount>/<path>#<key>` | the mount and path without the last segment: `vault://secret/shop/db#password` → `secret/shop`                             |
| a managed database's or cache's password         | `managed/<engine>`, such as `managed/postgres`                                                                             |
| an app's `.env` import                           | `apps/<app-slug>` (or the reference's group)                                                                               |

The words removed are `dev`, `development`, `staging`, `stage`, `prod`, `production`, `test` and
`qa`. A synced secret created with `POST /secrets/api/secrets` (or `dcloud secrets secrets create`)
also loses your own environments' slugs and names; one created by an app's `.env` import does not.

## Related

- [Secrets and versions](secrets-and-versions.md)
- `secrets.secrets.update` · `secrets.secrets.bulk-move` · `secrets.groups.list`
