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"]]]

Fields to expand in the response. Currently supports "permissions" to include the permissions field with the caller's permissions for the resource.

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
    }
  }
}