# Roles ## List `client.zones.roles.list(stringzoneID, RoleListParamsquery?, RequestOptionsoptions?): 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 - `zoneID: string` - `query: RoleListParams` - `after?: string` Cursor for forward pagination - `before?: string` Cursor for backward pagination - `expand?: "total_count" | Array<"total_count">` - `"total_count"` - `"total_count"` - `Array<"total_count">` - `"total_count"` - `identifier?: string` Filter roles by identifier - `limit?: number` Maximum number of items to return ### Returns - `RoleListResponse` - `items: Array` - `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" | "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?: string | null` Human-readable description - `pagination: Pagination` Cursor-based pagination metadata - `after_cursor: string | null` An opaque cursor used for paginating through a list of results - `before_cursor: string | null` An opaque cursor used for paginating through a list of results - `total_count?: number` Total number of items matching the query. Only included when expand[]=total_count is requested. ### Example ```typescript import KeycardAPI from '@keycardai/api'; const client = new KeycardAPI({ apiKey: process.env['KEYCARD_API_API_KEY'], // This is the default and can be omitted }); const roles = await client.zones.roles.list('zoneId'); console.log(roles.items); ``` ## Create `client.zones.roles.create(stringzoneID, RoleCreateParamsbody, RequestOptionsoptions?): 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 - `zoneID: string` - `body: RoleCreateParams` - `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. - `description?: string` Human-readable description ### Returns - `Role` A role that can be assigned to users within a zone. - `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" | "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?: string | null` Human-readable description ### Example ```typescript import KeycardAPI from '@keycardai/api'; const client = new KeycardAPI({ apiKey: process.env['KEYCARD_API_API_KEY'], // This is the default and can be omitted }); const role = await client.zones.roles.create('zoneId', { identifier: 'identifier' }); console.log(role.id); ``` ## Retrieve `client.zones.roles.retrieve(stringroleID, RoleRetrieveParamsparams, RequestOptionsoptions?): Role` **get** `/zones/{zoneId}/roles/{roleId}` Returns details of a specific role by ID ### Parameters - `roleID: string` - `params: RoleRetrieveParams` - `zoneId: string` Zone ID ### Returns - `Role` A role that can be assigned to users within a zone. - `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" | "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?: string | null` Human-readable description ### Example ```typescript import KeycardAPI from '@keycardai/api'; const client = new KeycardAPI({ apiKey: process.env['KEYCARD_API_API_KEY'], // This is the default and can be omitted }); const role = await client.zones.roles.retrieve('roleId', { zoneId: 'zoneId' }); console.log(role.id); ``` ## Update `client.zones.roles.update(stringroleID, RoleUpdateParamsparams, RequestOptionsoptions?): 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 - `roleID: string` - `params: RoleUpdateParams` - `zoneId: string` Path param: Zone ID - `description?: string | null` Body param: Human-readable description (set to null to unset) ### Returns - `Role` A role that can be assigned to users within a zone. - `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" | "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?: string | null` Human-readable description ### Example ```typescript import KeycardAPI from '@keycardai/api'; const client = new KeycardAPI({ apiKey: process.env['KEYCARD_API_API_KEY'], // This is the default and can be omitted }); const role = await client.zones.roles.update('roleId', { zoneId: 'zoneId' }); console.log(role.id); ``` ## Delete `client.zones.roles.delete(stringroleID, RoleDeleteParamsparams, RequestOptionsoptions?): void` **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 - `roleID: string` - `params: RoleDeleteParams` - `zoneId: string` Zone ID ### Example ```typescript import KeycardAPI from '@keycardai/api'; const client = new KeycardAPI({ apiKey: process.env['KEYCARD_API_API_KEY'], // This is the default and can be omitted }); await client.zones.roles.delete('roleId', { zoneId: 'zoneId' }); ``` ## Domain Types ### Role - `Role` A role that can be assigned to users within a zone. - `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" | "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?: string | null` Human-readable description ### Role Create - `RoleCreate` Schema for creating a new role - `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. - `description?: string` Human-readable description ### Role Update - `RoleUpdate` Schema for updating an existing role. The role identifier is immutable. - `description?: string | null` Human-readable description (set to null to unset)