Roles
A role is a bundle of permissions. Role assignment is the act of granting a role to a user on a project. The same user can hold different roles on different projects; a user with no role on a project can't see it at all.
Built-in roles
Every project ships with four built-in roles you can assign without defining anything custom:
| Role | What they can do |
|---|---|
viewer | Read every resource. No writes, no deletes. Right for monitoring tools, auditors. |
editor | Create + update most resources. Cannot manage IAM (users, roles, keys). Right for day-to-day developers. |
admin | Everything editor can do, plus IAM. Can create users, grant/revoke roles, manage API keys. |
billing-admin | Read invoices, change payment method, view + raise quota. No resource access. Right for finance. |
The admin role does not include billing-admin and vice versa. By design — the engineer who runs the API shouldn't also be the one approving the bill.
Granular roles
Beyond the four built-ins, we ship per-resource granular roles for the cases where editor is too much:
vms:operator— create / start / stop / destroy VMs only, no networkingstorage:operator— manage volumes, buckets, snapshots, backupsdns:admin— full DNS zone + record management; nothing elsenetworking:admin— networks, subnets, security groups, floating IPs, LBsdatabases:admin— managed databases + their backups
You assign these the same way as built-ins, via POST /v1/role-assignments.
Custom roles
Define your own at POST /v1/roles (not in the minimal sample below) by listing the permissions to bundle. Permission names follow the pattern <resource>:<action> — e.g. vms:read, volumes:create, databases:snapshot. The full permission catalog is at GET /v1/permissions.
Use cases for custom roles: "read everything except billing" for a security auditor; "manage DNS records but not zones" for a marketing team that owns subdomain content but not the zone delegation.
How role assignments compose
A user can hold multiple role assignments on one project. The effective permission set is the union — the role list is additive, not multiplicative. Granting viewer + vms:operator to the same user gives them read on everything + write on VMs specifically.
Revoking one role doesn't revoke the others. To strip a user completely, delete each assignment one at a time, or delete the user (which atomically revokes all assignments).
What's next
- Users — who you grant roles to.
- Projects — what you grant roles on.
- Authentication — how API keys map to user roles.