Diagnose: Permission secretmanager.versions.access denied

Symptom: "Permission 'secretmanager.versions.access' denied for resource projects/[P]/secrets/[S]/versions/[V]" (or PERMISSION_DENIED on access).

Cause: the calling identity lacks secretAccessor on that secret, or the version is disabled/destroyed.

Confirm in order:

1. gcloud secrets get-iam-policy [S] --project [P] - is the calling identity bound to roles/secretmanager.secretAccessor?
2. Which identity is calling? The workload's SA, not yours. Check the Cloud Run service's --service-account or the GCE SA.
3. gcloud secrets versions describe [V] --secret [S] - state must be ENABLED. Disabled or destroyed versions fail regardless of IAM.

Fix:

gcloud secrets add-iam-policy-binding [S] --project [P]   --member serviceAccount:[WORKLOAD-SA]   --role roles/secretmanager.secretAccessor

Prefer binding on the secret, not the project. Project-wide secretAccessor is overbroad.

Traps:

• Granting on the wrong secret name (typo) or wrong project. The error names the exact resource; copy it.
• The SA was just created: IAM propagation takes a minute or two.
• Using latest while a rotation disabled the newest version: pin a known-enabled version or re-enable.

Verify: call accesssecretversion as the workload identity (or deploy and read at startup) and confirm success without logging the value.

Verified 2026-09-26 on the Secret Manager access docs (resource name format, access pattern) and IAM docs (secretAccessor role, versions.access permission). Version states from the managing-secrets docs.