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.

Last updated 18 November 2026View as Markdown

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

  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.

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

  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.

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.

Did this page help you?