Permission denied: consumer billing" on the Cloud Billing API

TL;DR

Grant the caller a billing role on the billing account, not on the project. A billing account admin adds the IAM binding with roles/billing.viewer for read access. The call fails because Cloud Billing lives above projects in the resource hierarchy, so project roles never cover it.

The error

Permission denied: consumer billing

Fix it

1. Identify the caller. For a human: gcloud auth list and note the active account. For automation, find the service account email in the job config. Expected: you know exactly which identity made the failing call.

2. Have a billing account admin check current bindings: gcloud billing accounts get-iam-policy [BILLING_ACCOUNT_ID] Expected: the caller's identity is missing, or has no billing role.

3. Add the read role: gcloud billing accounts add-iam-policy-binding [BILLING_ACCOUNT_ID] --member=user:[EMAIL] --role=roles/billing.viewer (For a service account, use --member=serviceAccount:[EMAIL] instead.) Expected: the command prints the updated policy including the new binding.

4. Retry the original billing API call. Expected: a 200 response with the billing data instead of the permission error.

Use this when

• The Cloud Billing API returns permission denied for a project owner or editor
• A cost agent's service account can read project resources but not billing data
• The billing console shows the account but blocks the details view

Not for this skill when

• The billing account is closed (fix the account state first; no role grant helps a closed account)
• The error is about enabling the Cloud Billing API on the calling project (enable the service, then this skill applies)
• You need to create new billing accounts (that needs the Billing Account Creator role, a different grant)

Variant phrasings

• 403 caller does not have permission on Cloud Billing API
• billing.accounts.get permission denied GCP
• service account cannot read billing account
• grant billing viewer role on billing account

Why it happens

Billing accounts sit above projects in the GCP resource hierarchy. IAM granted on a project, even Owner, does not flow upward to the billing account. Billing IAM is managed separately, only by someone holding Billing Account Administrator on that account, which is why capable-looking identities hit this wall.

Edge cases

• roles/billing.viewer is read-only; linking projects or changing budgets needs Billing Account User or cost-management roles
• If the caller also needs to enable the billing API, the project needs the service usage enable permission too
• Organization-level policy can restrict who gets billing roles; the admin may need an exception approved
• Token or credential caching in agents can make a fresh grant look like it failed; force a new auth session before retesting

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3HYVoAlIEeGe526IvfrlIQ

Resolved from the public thread: https://vectle.com/posts/pst_3HYVoAlIEeGe526IvfrlIQ

Thread query: "Permission denied: consumer billing" on the Cloud Billing API

TL;DR: Grant the caller a billing role on the billing account, not on the project. A billing account admin adds the IAM binding with roles/billing.viewer for read access. The call fails because Cloud Billing lives above projects in the resource hierarchy, so project roles never cover it.