User and role reference

This page lists user fields and role naming guidance. For the concept, see Users and roles.

User fields

Field	Type	Required	Description
`id`	UUID string	Yes	Unique user identifier.
`alias`	string	Yes	Human-readable user name, often an email or username.
`publicKey`	string	Yes	Public key used for signing and authentication.
`lock`	enum	Yes	`Unlocked` or `Locked`.
`roles`	string array	Yes	Role names on the user, set by genesis, user invitation, `v0_CreateUser`, or `v0_UpdateUser`.
`loginIds`	array	No	Login provider identifiers. Include internal `harmonize` login and any configured external identity providers.
`description`	string	No	User description.
`customProperties`	object	Yes	String key-value metadata. Use `{}` when empty.

Role naming

Use role names that are stable, descriptive, and consistent. You do not create roles as separate governed resources; you can define a role name whenever you use it in users, policies, or domain read access.

Valid style	Avoid
`policy-operator`	`PolicyOperator`
`transaction-operator`	`transaction_operator`
`compliance`	`Compliance Team`

Role names used in policies must match user role assignments exactly. In the standard governed user-management flow, assigning a role name to a user or changing a user's roles requires an approved v0_CreateUser or v0_UpdateUser intent.

Role assignment lifecycle

Stage	Behavior
Define a role name	Use the role-name string in a user, policy, or domain read access configuration.
Assign during genesis	Include the role name in the genesis user's `roles` array.
Assign through invitation	Include the role name in the invitation user object's `roles` array.
Assign through user intent	Submit and approve a `v0_CreateUser` or `v0_UpdateUser` intent.
Remove from a user	Submit and approve a `v0_UpdateUser` intent with the updated `roles` array.

Lock values

Value	Behavior
`Unlocked`	User can act according to roles and policies.
`Locked`	User cannot create or approve intents.

Known role planning fields

When documenting a role model, record:

Field	Purpose
Role name	Exact string used in policies and users.
Domain	Where users with the role operate.
Maker workflows	Intents the role can create.
Checker workflows	Workflows the role can approve.
Minimum users	Number of users required to satisfy quorum.
Read access	Objects the role can view.