## List

**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.

### Path Parameters

- `zoneId: string`

### Query Parameters

- `after: optional string`

  Cursor for forward pagination

- `before: optional string`

  Cursor for backward pagination

- `"expand[]": optional "total_count" or array of "total_count"`

  - `UnionMember0 = "total_count"`

    - `"total_count"`

  - `UnionMember1 = array of "total_count"`

    - `"total_count"`

- `identifier: optional string`

  Filter roles by identifier

- `limit: optional number`

  Maximum number of items to return

### Returns

- `items: array of Role`

  - `id: string`

    Unique identifier of the role

  - `created_at: string`

    Entity creation timestamp

  - `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.

  - `owner_type: "platform" or "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: string`

    Entity update timestamp

  - `zone_id: string`

    Zone this role belongs to

  - `description: optional string`

    Human-readable description

- `pagination: object { after_cursor, before_cursor, total_count }`

  Cursor-based pagination metadata

  - `after_cursor: string`

    An opaque cursor used for paginating through a list of results

  - `before_cursor: string`

    An opaque cursor used for paginating through a list of results

  - `total_count: optional number`

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

### Example

```http
curl https://api.keycard.ai/zones/$ZONE_ID/roles \
    -H "Authorization: Bearer $KEYCARD_API_API_KEY"
```