# Roles ## List `client.Zones.Roles.List(ctx, zoneID, query) (*ZoneRoleListResponse, error)` **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 ZoneRoleListParams` - `After param.Field[string]` Cursor for forward pagination - `Before param.Field[string]` Cursor for backward pagination - `Expand param.Field[ZoneRoleListParamsExpandUnion]` - `type ZoneRoleListParamsExpandString string` - `const ZoneRoleListParamsExpandStringTotalCount ZoneRoleListParamsExpandString = "total_count"` - `type ZoneRoleListParamsExpandArray []string` - `const ZoneRoleListParamsExpandArrayItemTotalCount ZoneRoleListParamsExpandArrayItem = "total_count"` - `Identifier param.Field[string]` Filter roles by identifier - `Limit param.Field[int64]` Maximum number of items to return ### Returns - `type ZoneRoleListResponse struct{…}` - `Items []Role` - `ID string` Unique identifier of the role - `CreatedAt Time` 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. - `OwnerType RoleOwnerType` 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. - `const RoleOwnerTypePlatform RoleOwnerType = "platform"` - `const RoleOwnerTypeCustomer RoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this role belongs to - `Description string` Human-readable description - `Pagination ZoneRoleListResponsePagination` Cursor-based pagination metadata - `AfterCursor string` An opaque cursor used for paginating through a list of results - `BeforeCursor string` An opaque cursor used for paginating through a list of results - `TotalCount int64` Total number of items matching the query. Only included when expand[]=total_count is requested. ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) roles, err := client.Zones.Roles.List( context.TODO(), "zoneId", keycard.ZoneRoleListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", roles.Items) } ``` ## Create `client.Zones.Roles.New(ctx, zoneID, body) (*Role, error)` **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 ZoneRoleNewParams` - `RoleCreate param.Field[RoleCreate]` Schema for creating a new role ### Returns - `type Role struct{…}` A role that can be assigned to users within a zone. - `ID string` Unique identifier of the role - `CreatedAt Time` 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. - `OwnerType RoleOwnerType` 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. - `const RoleOwnerTypePlatform RoleOwnerType = "platform"` - `const RoleOwnerTypeCustomer RoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this role belongs to - `Description string` Human-readable description ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) role, err := client.Zones.Roles.New( context.TODO(), "zoneId", keycard.ZoneRoleNewParams{ RoleCreate: keycard.RoleCreateParam{ Identifier: "identifier", }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", role.ID) } ``` ## Retrieve `client.Zones.Roles.Get(ctx, roleID, query) (*Role, error)` **get** `/zones/{zoneId}/roles/{roleId}` Returns details of a specific role by ID ### Parameters - `roleID string` - `query ZoneRoleGetParams` - `ZoneID param.Field[string]` Zone ID ### Returns - `type Role struct{…}` A role that can be assigned to users within a zone. - `ID string` Unique identifier of the role - `CreatedAt Time` 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. - `OwnerType RoleOwnerType` 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. - `const RoleOwnerTypePlatform RoleOwnerType = "platform"` - `const RoleOwnerTypeCustomer RoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this role belongs to - `Description string` Human-readable description ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) role, err := client.Zones.Roles.Get( context.TODO(), "roleId", keycard.ZoneRoleGetParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", role.ID) } ``` ## Update `client.Zones.Roles.Update(ctx, roleID, params) (*Role, error)` **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 ZoneRoleUpdateParams` - `ZoneID param.Field[string]` Path param: Zone ID - `RoleUpdate param.Field[RoleUpdate]` Body param: Schema for updating an existing role. The role identifier is immutable. ### Returns - `type Role struct{…}` A role that can be assigned to users within a zone. - `ID string` Unique identifier of the role - `CreatedAt Time` 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. - `OwnerType RoleOwnerType` 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. - `const RoleOwnerTypePlatform RoleOwnerType = "platform"` - `const RoleOwnerTypeCustomer RoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this role belongs to - `Description string` Human-readable description ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) role, err := client.Zones.Roles.Update( context.TODO(), "roleId", keycard.ZoneRoleUpdateParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", role.ID) } ``` ## Delete `client.Zones.Roles.Delete(ctx, roleID, body) error` **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` - `body ZoneRoleDeleteParams` - `ZoneID param.Field[string]` Zone ID ### Example ```go package main import ( "context" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) err := client.Zones.Roles.Delete( context.TODO(), "roleId", keycard.ZoneRoleDeleteParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } } ``` ## Domain Types ### Role - `type Role struct{…}` A role that can be assigned to users within a zone. - `ID string` Unique identifier of the role - `CreatedAt Time` 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. - `OwnerType RoleOwnerType` 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. - `const RoleOwnerTypePlatform RoleOwnerType = "platform"` - `const RoleOwnerTypeCustomer RoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this role belongs to - `Description string` Human-readable description ### Role Create - `type RoleCreate struct{…}` 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 - `type RoleUpdate struct{…}` Schema for updating an existing role. The role identifier is immutable. - `Description string` Human-readable description (set to null to unset)