Create custom roles for Cloud Billing accounts

Identity and Access Management (IAM) includes fine-grained permissions, which lets you grant or revoke access to specific actions for individual users. To simplify the process of assigning permissions to users, IAM roles combine these fine-grained permissions into related groups. Billing has predefined roles , such as Billing Account Administrator or Billing Account Viewer, which work for most users. But, if they don't fit your needs, custom roles let you to grant more specific sets of permissions.

Create a custom role

Custom roles are created on the organization, and then are applied to any billing account in the organization. Creating and Managing Custom Roles in the IAM documentation describes how to configure a custom role, including which permissions are necessary.

After custom roles are created, you can grant custom roles to users just like standard, predefined roles. Learn how to update billing permissions .

Example custom role

Imagine you want to give someone the ability to edit cost management features, such as budget alerts and billing export. The relevant permissions are:

• billing.budgets.create
• billing.budgets.update
• billing.accounts.updateUsageExportSpec

With the predefined roles, to apply these permissions you need to grant the Billing Account Administrator role. But that role also includes permission to delete resource associations, cancel subscriptions, and close the billing account. If you didn't want your users to have those capabilities, you could instead create a custom role with only the three necessary permissions and name it Cost Management Administrator . Then, you could apply that custom role in combination with the Billing Account Viewer role to any users that should have broad cost management permissions but no ability to edit other account properties.

Permission association and inheritance

You can grant billing permissions at the billing account level or at the project level. Most billing permissions belong on the billing account, so roles containing those permissions should be associated with the billing account. Other billing permissions instead belong on a project and need to be associated with the project instead of the billing account.

For example, associating a project with a billing account requires the billing.resourceAssociations.create permission on the billing account and also the resourcemanager.projects.createBillingAssignment permission on the project. This is because project permissions are required for actions where project owners control access, while billing account permissions are required for actions where billing account administrators control access. When both are involved, both permissions are necessary.

Just like other IAM permissions, all billing permissions inherit from higher levels of the billing hierarchy. For example, a user with a role containing billing.accounts.close on an organization can close any billing account within that organization. However, some permissions only apply at higher levels. For example, the billing.accounts.list permission doesn't do anything when applied to an individual billing account, but a user with a role containing billing.accounts.list on an organization can list all billing accounts within that organization.

Billing activities

The following tables describe common billing activities, the permissions required to perform those activities, and the resource that those permissions apply to.

Account management

Action	Permission	Resource
Get basic account information (for example, account name, currency, or if the account is open or closed)	billing.accounts.get	Billing account
Upgrade from free trial	billing.accounts.update	Billing account
Rename account	billing.accounts.update	Billing account
Change purchase order number	billing.accounts.update	Billing account
Close account	billing.accounts.close	Billing account
Reopen closed account	billing.accounts.reopen	Billing account

Billing account hierarchy

Cost information

Cost view permissions can be limited to specific projects, or granted on a billing account to view all costs for a billing account.

Payment information

The payment profile includes customer name, address, and payment method.

Action	Permission	Resource
View payment profile	billing.accounts.getPaymentInfo	Billing account
Update payment profile	billing.accounts.updatePaymentInfo	Billing account
View prices only for the SKUs that have incurred usage	billing.accounts.getPricing	Billing account
View custom contract prices per SKU for a billing account	billing.accounts.getPricing	Billing account
View costs and usage for a billing account	billing.accounts.getSpendingInformation	Billing account

Resource associations

Moving a project between billing accounts requires the same permissions as removing it from the original billing account and associating it with the new one.

Budgets and spending alerts

Credits and promotions

Policy

The policy defines which users have access to which resources on a billing account. For information on creating or modifying custom roles, see the Create a Custom Role section, above.

Action	Permission	Resource
View roles on account, including associated usernames	billing.accounts.getIamPolicy	Billing account
Give roles to users on account	billing.accounts.setIamPolicy	Billing account

Export specifications

The export specification defines where to send a copy of all usage-related data, and can contain the name of a BigQuery dataset .

Action	Permission	Resource
View current export specification (Cloud Storage bucket or BigQuery dataset to export usage data to)	billing.accounts.getUsageExportSpec	Billing account
Modify export specification	billing.accounts.updateUsageExportSpec	Billing account

Related topics

• Overview of Cloud Billing access control
• Cloud Billing API access control
• Granting, changing, and revoking Access