Skip to content
Docs
Roles
List

List group role assignments

API Reference
Zones
Groups
Roles

List group role assignments

GET/zones/{zoneId}/groups/{groupId}/roles

Returns the roles assigned to the group. Members inherit these roles. Returns the shared role-assignment shape with principal_type set to group. Use cursor pagination via after/before; pass expand[]=total_count to include the matching row count. Pass filter[id] (repeatable, max 100) to restrict results to a known set of role assignments, mutually exclusive with after/before (returns 400 if combined). When filter[id] is set, limit is ignored and the response contains every requested assignment that exists on the group, in a single page. IDs not on the group are silently omitted.

Path ParametersExpand Collapse
zoneId: string
groupId: string
Query ParametersExpand Collapse
after: optional string

Cursor for forward pagination

minLength1
maxLength255
before: optional string

Cursor for backward pagination

minLength1
maxLength255
"expand[]": optional "total_count" or array of "total_count"
Accepts one of the following:
UnionMember0 = "total_count"
UnionMember1 = array of "total_count"
"filter[id]": optional string or array of string

Restrict results to the role assignment with this ID. Repeatable, max 100. Mutually exclusive with after/before.

Accepts one of the following:
UnionMember0 = string

Restrict results to the role assignment with this ID. Repeatable, max 100. Mutually exclusive with after/before.

UnionMember1 = array of string
limit: optional number

Maximum number of items to return

minimum1
maximum100
ReturnsExpand Collapse
items: array of RoleAssignment { id, created_at, principal_id, 8 more }
id: string

Unique identifier of the role assignment

created_at: string

Entity creation timestamp

formatdate-time
principal_id: string

ID of the principal the role is assigned to (a user, application, or group ID).

principal_type: string

The kind of principal the role is assigned to: user, application, or group. A role assigned to a group is inherited by that group's members.

role_id: string

ID of the assigned role

role_identifier: string

Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.

minLength1
maxLength255
role_owner_type: "platform" or "customer"

Owner type of the assigned role. Disambiguates roles that share an identifier across owner types.

Accepts one of the following:
"platform"
"customer"
updated_at: string

Entity update timestamp

formatdate-time
zone_id: string

Zone this assignment belongs to

scope_id: optional string

The ID of the scoped resource. Null when the assignment is unscoped.

scope_type: optional string

The kind of resource this grant is scoped to (e.g. zone). Null when the assignment is unscoped (applies to the owning zone itself).

List group role assignments

curl https://api.keycard.ai/zones/$ZONE_ID/groups/$GROUP_ID/roles \
    -H "Authorization: Bearer $KEYCARD_API_API_KEY"
{
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "principal_id": "principal_id",
      "principal_type": "principal_type",
      "role_id": "role_id",
      "role_identifier": "role_identifier",
      "role_owner_type": "platform",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "zone_id": "zone_id",
      "scope_id": "scope_id",
      "scope_type": "scope_type"
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}
Returns Examples
{
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "principal_id": "principal_id",
      "principal_type": "principal_type",
      "role_id": "role_id",
      "role_identifier": "role_identifier",
      "role_owner_type": "platform",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "zone_id": "zone_id",
      "scope_id": "scope_id",
      "scope_type": "scope_type"
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}