Roles

Roles let you control what members of your organization can do. A role is a named bundle of permissions; a member’s effective access is the union of the permissions across every role they hold.

The authenticated caller can read their own resolved access from the identity service’s GetMyUser response, whose permissions field lists the effective permission keys (e.g. INTEGRATIONS_WRITE) granted by their assigned roles.

Every organization starts with a single seeded system role, Admin, which holds every permission and cannot be edited or deleted. You create additional roles, choose which permissions each grants, pick one as the default assigned to new members, and assign roles to individual members.

Service: firetiger.rbac.v1.RolesService

Resource name pattern: roles/{role_id}

Access: Read-write

Resource type: Role

Two rules are enforced on every mutation:

  • No privilege escalation. You can only grant permissions that you hold yourself. Creating or editing a role, changing the default role, or assigning a role whose permissions exceed your own is rejected with permission_denied.
  • Last-admin guardrail. An organization must always retain at least one member holding the system Admin role. A change that would remove the final admin is rejected with failed_precondition.

Example flow

Create a role, make it the default for new members, then assign it to a user.

1. Create a role

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/CreateRole" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "integrations-owner",
    "role": {
      "display_name": "Integrations Owner",
      "description": "Manages connections and integrations",
      "permissions": ["INTEGRATIONS_WRITE"]
    }
  }'

{
  "role": {
    "name": "roles/integrations-owner",
    "displayName": "Integrations Owner",
    "description": "Manages connections and integrations",
    "permissions": ["INTEGRATIONS_WRITE"],
    "system": false,
    "isDefault": false,
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

2. Assign the role to a member

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/AssignRoles" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "users/u-a1b2c3",
    "roles": ["roles/integrations-owner"]
  }'

{
  "roles": ["roles/integrations-owner"]
}

Methods

Method Description
CreateRole Create a new role
GetRole Retrieve a single role
ListRoles List roles in your organization
UpdateRole Edit a role’s name, description, or permissions
DeleteRole Soft-delete a role
ListUsersWithPermission Find members holding a permission
SetDefaultRole Choose the default role for new members
AssignRoles Replace a member’s role assignments

CreateRole

Creates a new role in your organization.

POST /firetiger.rbac.v1.RolesService/CreateRole

Request body

Field Type Required Description
role_id string   Optional kebab-case slug for the resource name (roles/{role_id}). Must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$. If omitted, the server generates one.
role Role Yes The role to create. Only display_name, description, and permissions are read; server-managed fields are ignored.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/CreateRole" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "billing-manager",
    "role": {
      "display_name": "Billing Manager",
      "permissions": ["BILLING_WRITE"]
    }
  }'

Response

{
  "role": {
    "name": "roles/billing-manager",
    "displayName": "Billing Manager",
    "permissions": ["BILLING_WRITE"],
    "system": false,
    "isDefault": false,
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

GetRole

Retrieves a single role by resource name.

POST /firetiger.rbac.v1.RolesService/GetRole

Request body

Field Type Required Description
name string Yes Role resource name (roles/{role_id})

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/GetRole" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "roles/integrations-owner"}'

Response

{
  "role": {
    "name": "roles/integrations-owner",
    "displayName": "Integrations Owner",
    "permissions": ["INTEGRATIONS_WRITE"],
    "system": false,
    "isDefault": false,
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

ListRoles

Lists roles in your organization.

POST /firetiger.rbac.v1.RolesService/ListRoles

Request body

Field Type Required Description
filter string   AIP-160 filter expression
order_by string   Sort order (e.g. create_time desc)
page_size integer   Maximum results per page
page_token string   Token from a previous next_page_token
show_deleted boolean   Include soft-deleted roles when true

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/ListRoles" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "roles": [
    {
      "name": "roles/admin",
      "displayName": "Admin",
      "system": true,
      "isDefault": true,
      "createTime": "2024-01-01T00:00:00Z",
      "updateTime": "2024-01-01T00:00:00Z"
    },
    {
      "name": "roles/integrations-owner",
      "displayName": "Integrations Owner",
      "permissions": ["INTEGRATIONS_WRITE"],
      "system": false,
      "isDefault": false,
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}

UpdateRole

Edits a role’s display name, description, or permissions. The system Admin role cannot be edited (rejected with failed_precondition). Server-managed fields (system, is_default, name, timestamps) are ignored even if included in update_mask.

POST /firetiger.rbac.v1.RolesService/UpdateRole

Request body

Field Type Required Description
role Role Yes The role with name set and the fields to change
update_mask string   Comma-separated field paths to modify (display_name, description, permissions). Omitted or * updates all mutable fields.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/UpdateRole" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "role": {
      "name": "roles/integrations-owner",
      "permissions": ["INTEGRATIONS_WRITE", "CHANGE_MONITOR_WRITE"]
    },
    "update_mask": "permissions"
  }'

Response

{
  "role": {
    "name": "roles/integrations-owner",
    "displayName": "Integrations Owner",
    "permissions": ["INTEGRATIONS_WRITE", "CHANGE_MONITOR_WRITE"],
    "system": false,
    "isDefault": false,
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T15:00:00Z"
  }
}

DeleteRole

Soft-deletes a role. Rejected with failed_precondition when the role is the system Admin role or the current default role (change the default with SetDefaultRole first). Members who still held the role lose its permissions on their next request.

POST /firetiger.rbac.v1.RolesService/DeleteRole

Request body

Field Type Required Description
name string Yes Role resource name (roles/{role_id})

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/DeleteRole" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "roles/integrations-owner"}'

Response

{}

ListUsersWithPermission

Returns the members of your organization whose combined role permissions include a given permission. Useful for audits and for answering “who can do X?”.

POST /firetiger.rbac.v1.RolesService/ListUsersWithPermission

Request body

Field Type Required Description
permission Permission Yes The permission to query
page_size integer   Maximum results per page
page_token string   Token from a previous next_page_token

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/ListUsersWithPermission" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"permission": "INTEGRATIONS_WRITE"}'

Response

{
  "users": ["users/u-a1b2c3", "users/u-d4e5f6"],
  "nextPageToken": ""
}

SetDefaultRole

Atomically makes a role the default assigned to new members, clearing the flag from the previous default. Subject to the no-privilege-escalation rule: the target role’s permissions must be a subset of your own.

POST /firetiger.rbac.v1.RolesService/SetDefaultRole

Request body

Field Type Required Description
name string Yes Role resource name to make default (roles/{role_id})

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/SetDefaultRole" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "roles/integrations-owner"}'

Response

{
  "role": {
    "name": "roles/integrations-owner",
    "displayName": "Integrations Owner",
    "permissions": ["INTEGRATIONS_WRITE"],
    "system": false,
    "isDefault": true,
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T15:30:00Z"
  }
}

AssignRoles

Replaces a member’s entire set of role assignments with the provided list. The set is order-independent and deduplicated by the server. An empty list leaves the member with no roles. Subject to the no-privilege-escalation rule and the last-admin guardrail; there is no separate demote method, remove the Admin role from the list to demote a member.

POST /firetiger.rbac.v1.RolesService/AssignRoles

Request body

Field Type Required Description
user string Yes Target member resource name (users/{user})
roles string[]   Role resource names to assign. Every role must exist and belong to your organization.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.rbac.v1.RolesService/AssignRoles" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "users/u-a1b2c3",
    "roles": ["roles/integrations-owner", "roles/billing-manager"]
  }'

Response

{
  "roles": ["roles/billing-manager", "roles/integrations-owner"]
}
This site uses Just the Docs, a documentation theme for Jekyll.