# User and role reference

This page lists user fields and role naming guidance. For the concept, see [Users and roles](/products/custody/governance/users).

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


For examples, see [User and role examples](/products/custody/governance/users/examples).