FAQ

Secrets Manager FAQ and limits

Frequently asked questions

What are the prerequisites for Secrets Manager?

You need both secrets and kms feature gates enabled, a regional KMS endpoint, and at least one active symmetric KMS key. See Getting started.

Can I change the KMS key on an existing secret?

No. The KMS key binding is set at creation and is immutable. To use a different key, create a new secret (at a new path or after deleting the existing one).

Can I rename a secret?

No. The path is the identity and cannot be changed. Delete the secret and create a new one at the desired path if you need to reorganise.

Is delete reversible?

No. Delete is permanent from the customer’s perspective. There is no cancel-deletion or recovery API. The path becomes available for reuse after deletion.

Why do metadata APIs work but reveal fails?

The bound KMS key is likely disabled or pending deletion. Metadata APIs do not require crypto; getSecretValue and putSecretValue return 400 when the key is not active. See KMS integration.

What is the difference between metadata and value APIs?

List and get metadata return path, description, labels, version history, and timestamps — never secret values. Use getSecretValue to reveal decrypted values. This separation lets you grant auditors metadata access without reveal permission.

Are list and browse results filtered by IAM?

Yes. Even with list permission, results only include paths where the caller also has read. Revealing values requires explicit getSecretValue on each path.

Does Secrets Manager work across regions?

No. Secrets exist in exactly one region. All API calls must target that region’s path.

Limits

Constraint	Limit
Path length	1–512 characters
Single string (`secretString`)	1–4096 decoded bytes (base64 on wire)
Generated secret (`byteLength`)	16–4096 bytes
Key/value: keys per version	Up to 256
Key/value: key name	1–128 chars, `[A-Za-z0-9_.-]`
Key/value: each value	1–4096 decoded bytes (base64 on wire)
Key/value: total decoded size	≤ 65,536 bytes across all keys

Path rules

Rule	Value
Must start with	`/`
Trailing `/`	Not allowed
Double slashes	Not allowed
Allowed characters	`A–Z`, `a–z`, `0–9`, `/`, `_`, `-`, `.`, `+`

See Paths and naming for examples.

Troubleshooting

HTTP status	Typical cause	What to do
`403`	`secrets` or `kms` feature gate disabled; IAM denied; access policy denied	Verify feature gates, role bindings, and access policy conditions
`404`	Secret, version, or KMS key not found; wrong project scope	Verify path, region, project header, and that the resource exists
`400`	Invalid path; KMS key disabled; version destroyed; invalid base64 or size limits	Check path format, KMS key status, version status, and payload size
`409`	Secret path already exists in org/region/project scope	Choose a different path or delete the existing secret first
`503`	KMS not available in the region	Use a different region or contact support about regional KMS availability