# Roles ## 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) ``` ## Create `zones.roles.create(strzone_id, RoleCreateParams**kwargs) -> Role` **post** `/zones/{zoneId}/roles` Creates a new customer-owned role in the specified zone. The owner_type is always customer; platform roles are managed by Keycard. ### Parameters - `zone_id: str` - `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. - `description: Optional[str]` Human-readable description ### Returns - `class Role: …` A role that can be assigned to users within a zone. - `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 ### 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 ) role = client.zones.roles.create( zone_id="zoneId", identifier="identifier", ) print(role.id) ``` ## Retrieve `zones.roles.retrieve(strrole_id, RoleRetrieveParams**kwargs) -> Role` **get** `/zones/{zoneId}/roles/{roleId}` Returns details of a specific role by ID ### Parameters - `zone_id: str` - `role_id: str` ### Returns - `class Role: …` A role that can be assigned to users within a zone. - `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 ### 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 ) role = client.zones.roles.retrieve( role_id="roleId", zone_id="zoneId", ) print(role.id) ``` ## Update `zones.roles.update(strrole_id, RoleUpdateParams**kwargs) -> Role` **patch** `/zones/{zoneId}/roles/{roleId}` Updates a customer-owned role's description. The identifier is immutable, and platform-owned roles cannot be modified. ### Parameters - `zone_id: str` - `role_id: str` - `description: Optional[str]` Human-readable description (set to null to unset) ### Returns - `class Role: …` A role that can be assigned to users within a zone. - `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 ### 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 ) role = client.zones.roles.update( role_id="roleId", zone_id="zoneId", ) print(role.id) ``` ## Delete `zones.roles.delete(strrole_id, RoleDeleteParams**kwargs)` **delete** `/zones/{zoneId}/roles/{roleId}` Permanently deletes a customer-owned role. Platform-owned roles cannot be deleted, and a role with existing assignments returns 409. ### Parameters - `zone_id: str` - `role_id: str` ### 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 ) client.zones.roles.delete( role_id="roleId", zone_id="zoneId", ) ``` ## Domain Types ### Role - `class Role: …` A role that can be assigned to users within a zone. - `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 ### Role Create - `class RoleCreate: …` Schema for creating a new role - `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. - `description: Optional[str]` Human-readable description ### Role Update - `class RoleUpdate: …` Schema for updating an existing role. The role identifier is immutable. - `description: Optional[str]` Human-readable description (set to null to unset)