## List

`zones.roles.list(strzone_id, RoleListParams**kwargs)  -> RoleListResponse`

**get** `/zones/{zoneId}/roles`

Returns the roles defined in the specified zone. The full result set is currently returned in a single page; the `after`/`before`/`limit` cursor parameters are reserved and not yet enforced, and `pagination` cursors are always null.

### Parameters

- `zone_id: str`

- `after: Optional[str]`

  Cursor for forward pagination

- `before: Optional[str]`

  Cursor for backward pagination

- `expand: Optional[Union[Literal["total_count"], List[Literal["total_count"]]]]`

  - `Literal["total_count"]`

    - `"total_count"`

  - `List[Literal["total_count"]]`

    - `"total_count"`

- `identifier: Optional[str]`

  Filter roles by identifier

- `limit: Optional[int]`

  Maximum number of items to return

### Returns

- `class RoleListResponse: …`

  - `items: List[Role]`

    - `id: str`

      Unique identifier of the role

    - `created_at: datetime`

      Entity creation timestamp

    - `identifier: str`

      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.

    - `owner_type: Literal["platform", "customer"]`

      Who owns this role. Platform-owned roles are managed by Keycard and cannot be modified or deleted via the API; customer-owned roles are user-created.

      - `"platform"`

      - `"customer"`

    - `updated_at: datetime`

      Entity update timestamp

    - `zone_id: str`

      Zone this role belongs to

    - `description: Optional[str]`

      Human-readable description

  - `pagination: Pagination`

    Cursor-based pagination metadata

    - `after_cursor: Optional[str]`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: Optional[str]`

      An opaque cursor used for paginating through a list of results

    - `total_count: Optional[int]`

      Total number of items matching the query. Only included when expand[]=total_count is requested.

### Example

```python
import os
from keycardai_api import KeycardAPI

client = KeycardAPI(
    api_key=os.environ.get("KEYCARD_API_API_KEY"),  # This is the default and can be omitted
)
roles = client.zones.roles.list(
    zone_id="zoneId",
)
print(roles.items)
```