List available roles

organizations.list_roles(, ) -> OrganizationListRolesResponse

GET/organizations/{organization_id}/roles

Returns the list of available roles in the system for the organization. This includes both organization-level roles (e.g., org_admin, org_member) and zone-level roles (e.g., zone_manager, zone_viewer).

Each role includes:

name: Internal identifier (e.g., org_admin, zone_manager)
label: Human-readable display name (e.g., Organization Administrator)
scope: Whether the role applies at organization or zone level

ParametersExpand Collapse

organization_id: str

Organization ID or label identifier

minLength1

maxLength255

expand: Optional[List[Literal["permissions", "total_count"]]]

Fields to expand in the response. Supports "permissions" to include the permissions field with the caller's permissions for the resource. For list organization identities only, "total_count" populates pagination.total_count with the number of identities matching the same filters as the list (excluding cursor and limit). Other operations ignore expand values they do not use.

Accepts one of the following:

"permissions"

"total_count"

scope: Optional[RoleScope]

Filter roles by scope (organization or zone level)

Accepts one of the following:

"organization"

"zone"

x_client_request_id: Optional[str]

formatuuid

ReturnsExpand Collapse

class OrganizationListRolesResponse: …

List of available roles

items: List[Item]

List of roles

description: str

Detailed description of the role and its permissions

maxLength500

label: str

Human-readable display name for the role

maxLength128

name: str

Internal identifier for the role (e.g., org_admin, zone_manager)

scope: RoleScope

The scope at which this role can be assigned (organization or zone)

Accepts one of the following:

"organization"

"zone"

permissions: Optional[Dict[str, Dict[str, bool]]]

Permissions granted to the authenticated principal for this resource. Only populated when the 'expand[]=permissions' query parameter is provided. Keys are resource types (e.g., "organizations"), values are objects mapping permission names to boolean values indicating if the permission is granted.

List available roles

from keycardai_api import KeycardAPI

client = KeycardAPI()
response = client.organizations.list_roles(
    organization_id="x",
)
print(response.items)

{
  "items": [
    {
      "description": "Full administrative access to all organization resources",
      "label": "Organization Administrator",
      "name": "org_admin",
      "scope": "organization"
    }
  ],
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}

Returns Examples

{
  "items": [
    {
      "description": "Full administrative access to all organization resources",
      "label": "Organization Administrator",
      "name": "org_admin",
      "scope": "organization"
    }
  ],
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}