Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.halite-app.com/llms.txt

Use this file to discover all available pages before exploring further.

The Users & Roles section of Halite lets you create and manage console accounts, assign roles, build custom roles with fine-grained verb:resource permissions, reset passwords, and deactivate users — all from the admin UI. For a conceptual overview of how permissions are evaluated, see RBAC.
All user and role management operations require the manage_user:user:* or manage_role:role:* permission. These are granted only to the built-in admin role. Do not share admin credentials with operators who should have limited access.

​
Users

Table of Halite users with username, display name, email, active badge, and last login timestamp

​
User fields

Each user account has the following attributes:
FieldDescription
usernameUnique login name (1–255 characters)
display_nameHuman-readable name shown in the UI (optional)
emailOptional email address
is_activeIf false, the user cannot log in
is_builtinBuilt-in users (e.g. the initial admin) cannot be deleted
must_change_pwIf true, the user is forced to change their password on next login
created_atAccount creation timestamp
last_login_atMost recent successful login

​
Creating a user

1

Open Users

Click Settings → Users in the admin sidebar.
2

Click New User

Fill in the username (required), display name, email, and initial password (minimum 8 characters). Leave Must change password checked so the user sets their own password on first login.
3

Assign roles (optional)

Select one or more roles from the role picker. You can also assign roles later from the user detail panel.
4

Save

Click Create. The new user appears in the list immediately. The action is recorded in the audit log.

​
Updating a user

You can change a user’s display_name, email, or is_active status via PATCH /api/users/{user_id}. You cannot change a user’s username after creation. To deactivate a user, set is_active to false. Deactivated users cannot log in and any existing sessions are preserved until they expire naturally. To terminate active sessions immediately, trigger a password reset (which calls end_sessions_for_user on the backend).

​
Resetting a password

POST /api/users/{user_id}/password with a new_password (minimum 8 characters) and must_change_pw flag. Setting a new password terminates all existing sessions for the target user.

​
Deleting a user

Built-in users cannot be deleted — the API returns 409 Conflict. You also cannot delete your own account. Deletions are permanent; the audit log retains a record of all actions the deleted user performed.

​
Roles

Role detail panel with name, is_builtin badge, and a table of verb/resource_glob permission rows

​
Built-in roles

Halite ships three built-in roles that cannot be deleted:
RolePermissions (summary)
admin*:* — full access to everything
operatorview:*, run:*, execute and key management, kill jobs
viewerview on minion, key, job, grain, pillar, event, setting, and inventory resources

​
Custom roles

Create a custom role with POST /api/roles (requires manage_role:role:*). Provide a name (1–64 characters) and optional description. Once created, add permissions one at a time with POST /api/roles/{role_id}/permissions: 
{
  "verb": "view",
  "resource_glob": "inventory:*"
}
The resource_glob is matched against the resource path at request time using glob semantics. For example, "job:*" matches any job resource. Remove an individual permission with DELETE /api/roles/{role_id}/permissions/{permission_id}. Built-in roles cannot be deleted and their permissions cannot be modified.

​
Assigning roles to users

POST /api/users/{user_id}/roles with {"role_id": "<uuid>"}. A user can hold multiple roles — permissions are unioned across all of them. Remove a role assignment with DELETE /api/users/{user_id}/roles/{role_id}.

​
Example: creating a read-only inventory auditor

1

Create a custom role

Go to Settings → Roles and click New Role. Name it inventory-auditor.
2

Add permissions

Add one permission: verb = view, resource_glob = inventory:*. This is the same permission the viewer role has for inventory.
3

Create the user and assign the role

Create a new user account and assign the inventory-auditor role. The user can now browse the Inventory page but cannot trigger a refresh or access any other sensitive areas.

​
Permissions

​
User routes (/api/users)

RouteRequired permission
GET /api/usersview:user:*
GET /api/users/{user_id}view:user:*
POST /api/usersmanage_user:user:*
PATCH /api/users/{user_id}manage_user:user:*
DELETE /api/users/{user_id}manage_user:user:*
POST /api/users/{user_id}/passwordmanage_user:user:*
GET /api/users/{user_id}/rolesview:user:*
POST /api/users/{user_id}/rolesmanage_user:user:*
DELETE /api/users/{user_id}/roles/{role_id}manage_user:user:*

​
Role routes (/api/roles)

RouteRequired permission
GET /api/rolesview:role:*
GET /api/roles/{role_id}view:role:*
POST /api/rolesmanage_role:role:*
PATCH /api/roles/{role_id}manage_role:role:*
DELETE /api/roles/{role_id}manage_role:role:*
POST /api/roles/{role_id}/permissionsmanage_role:role:*
DELETE /api/roles/{role_id}/permissions/{permission_id}manage_role:role:*
Both manage_user and manage_role are granted exclusively to the built-in admin role.