Manage role bindings

This guide shows you how to grant, revoke, list, and test fine-grained IAM access using role bindings.

Role binding commands aren't available in the evroc CLI. Use the IAM API for role binding management.

Prerequisites

Before you manage role bindings, you'll need:

The evroc CLI installed and logged in. See Install the evroc CLI.
Permission to manage role bindings in the target project or organization.
The project ID or organization ID where you want to grant access.
The principal FQID for the user or service account receiving access.

Get an access token for the API examples:

TOKEN="$(evroc iam get-access-token)"

List available roles

List predefined roles before you grant access. The response includes each role's scope and permissions.

curl -H "Authorization: Bearer $TOKEN" \
  https://api.evroc.com/iam/v1beta1/roles

Use the role's id value when granting access, for example /iam/roles/computeOperator.

For descriptions of each predefined role and permission, see permissions and roles.

Grant a project role

Grant a role to a principal in a project with the assign endpoint. This creates the principal's role binding if it doesn't already exist.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "/iam/users/5a9bb4ea-a79f-4918-9b62-a983b576799e",
    "role": "/iam/roles/computeOperator"
  }' \
  https://api.evroc.com/iam/v1beta1/projects/my-project/roleBindings/assign

The principal receives the role on every applicable resource in my-project.

Note: Assigning a role is idempotent. If the principal already has that role in the scope, the request replaces the role's resource list.

Grant access to specific resources

Add resources to limit a role to specific resource FQIDs.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "/iam/users/5a9bb4ea-a79f-4918-9b62-a983b576799e",
    "role": "/iam/roles/computeOperator",
    "resources": [
      "/compute/projects/my-project/regions/se-sto/virtualMachines/my-vm",
      "/compute/projects/my-project/regions/se-sto/virtualMachines/*"
    ]
  }' \
  https://api.evroc.com/iam/v1beta1/projects/my-project/roleBindings/assign

Use exact resource FQIDs for individual resources. Use * to match one path segment, such as all VMs in one region.

Grant an organization role

Grant organization-level roles on an organization scope.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "/iam/users/5a9bb4ea-a79f-4918-9b62-a983b576799e",
    "role": "/iam/roles/<organization-role-id>"
  }' \
  https://api.evroc.com/iam/v1beta1/organizations/my-org/roleBindings/assign

Replace <organization-role-id> with a role ID from the roles API.

Organization roles govern organization-level IAM operations. They don't grant access to resources inside projects.

List role bindings

List all role bindings in a project:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.evroc.com/iam/v1beta1/projects/my-project/roleBindings

List all role bindings in an organization:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.evroc.com/iam/v1beta1/organizations/my-org/roleBindings

Use the metadata.id value from the response when you need to get, patch, or delete a specific role binding.

Revoke one role

Remove one role from a principal with the revoke endpoint.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "/iam/users/5a9bb4ea-a79f-4918-9b62-a983b576799e",
    "role": "/iam/roles/computeOperator"
  }' \
  https://api.evroc.com/iam/v1beta1/projects/my-project/roleBindings/revoke

Revoking a role is idempotent. If the principal doesn't have the role, the request still succeeds. If no roles remain in the binding, the binding is deleted.

Delete all roles for a principal

Delete a role binding to revoke every role it grants to the principal in that scope.

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://api.evroc.com/iam/v1beta1/projects/my-project/roleBindings/alice-access

Replace alice-access with the role binding ID from metadata.id.

Warning: Deleting a role binding revokes every role in that binding for the principal on the selected scope.

Test your permissions

Use testPermissions to check whether the authenticated caller has specific permissions on specific resources. This is useful when you need to tailor an application UI to the caller's access.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checks": [
      {
        "permission": "compute.virtualMachines.start",
        "resource": "/compute/projects/my-project/regions/se-sto/virtualMachines/my-vm"
      },
      {
        "permission": "iam.roleBindings.read",
        "resource": "/iam/projects/my-project"
      }
    ]
  }' \
  https://api.evroc.com/iam/v1beta1/testPermissions

The response returns one result for each check, in the same order as the request.

{
  "results": [
    {
      "permission": "compute.virtualMachines.start",
      "resource": "/compute/projects/my-project/regions/se-sto/virtualMachines/my-vm",
      "allowed": true
    },
    {
      "permission": "iam.roleBindings.read",
      "resource": "/iam/projects/my-project",
      "allowed": false
    }
  ]
}

Check another principal's access

Use checkAccess to evaluate another principal's access.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "/iam/projects/my-project/serviceAccounts/ci-robot",
    "checks": [
      {
        "permission": "compute.virtualMachines.start",
        "resource": "/compute/projects/my-project/regions/se-sto/virtualMachines/my-vm"
      }
    ]
  }' \
  https://api.evroc.com/iam/v1beta1/checkAccess

You need permission to read role bindings on the scope to inspect another principal. If you don't have that permission, the request returns 404 so the scope's existence isn't revealed.

evroc User Documentation