Reference → Users — Reference

Users — Reference

The Users surface is the access-control plane for every SGEN site. It owns operator identity, profile data, role assignment, password lifecycle, and impersonation. Anything that authenticates against /sg-admin traces back to a record managed here.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a permission model. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Users live under the Users module in SG-Admin. The module renders three primary views — the user list, the user create / edit form, and the self-profile editor — and exposes a small set of write operations for create, update, password change, soft delete, restore, and permanent delete.

The module is paired by convention: one half renders the views and prepares the data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.

A second surface — operator impersonation — lives adjacent to the Users module under the platform's general admin-actions surface. It allows an authorized operator to switch into another user's session and switch back. Impersonation is included here because the entry points are listed inside the user list view, even though the implementation file is separate.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Users
URL prefix: /sg-admin/users/
View templates: application/views/Admin/Users/

The module surface is intentionally small. Heavier authorization (per-role capabilities, per-site member grants, billing-tier seat limits) lives in adjacent surfaces (Settings, SG-Dashboard, Subscription wizard) — this page covers only the user-record CRUD plane.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Users [+ Add new] │├──────────────────────────────────────────────────────────────────────┤│ Name Email Role Last seen ││ ──────────────── ────────────────────── ────────── ──────────────││ Jerome Cruz jerome@sgen.com Admin 2 min ago ││ James Compton james@jamescompton.com Editor 3 days ago ││ Maria Reyes maria@sgen.com Viewer 11 days ago ││ Sandbox Operator sandbox@sgen.com Admin now ││ ││ [⋯ Edit] [⋯ Switch to user] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Users surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

List and search

Returns the user records visible to the current operator, paginated, with role, email, last-seen, and status columns. Supports column sort, free-text filter, and per-page count. Driven by the data-table contract used across SG-Admin modules — responses arrive as a row collection plus a total count, suitable for direct binding to a paged grid.

Create user

Opens an empty profile form. Required fields at minimum: name, email, password, role. Optional fields cover phone, avatar, locale, and per-module access flags. On submit, the surface validates uniqueness of email, hashes the password, persists the record, and returns the new identifier.

Edit user

Loads an existing record into the same form shape used for create, pre-populated. Submit replaces the stored profile with the posted values; fields left blank do not clear server-side values (the form is partial-update by default).

Edit own profile

A reduced version of the edit form, scoped to the calling operator. Email and role are read-only; password is the only sensitive field exposed. Lives at a separate URL so role-restricted operators can update themselves without holding the broader edit capability.

Change password

A dedicated write path. Accepts the current password and a new password, validates length and complexity, and rewrites the hash. Returns success or a structured failure naming the rule that rejected the value (too short, missing class, matches previous).

Soft delete

Marks the record inactive without removing it from the database. Soft-deleted users disappear from the default list view but remain queryable via the inactive filter. Their authored content (pages, posts, media uploads) remains attributed to the deleted account.

Restore

Reverses a soft delete. The record returns to the active list with its prior role and profile intact.

Permanent delete

Hard-removes the record. Available only after a soft delete. Authored content is re-attributed to a fallback system account (configured under Settings → General). This path is irreversible and should be wired behind a confirmation prompt in any integration that exposes it.

Switch to user (impersonation)

Replaces the current session with a session as the target user. The original session is preserved server-side so that Switch back restores it. Impersonation is audit-logged — every entry and exit writes an Activity Log event with both operator identifiers. Some roles are excluded from being switched into; the surface returns a structured rejection when that rule fires.

Switch back

Restores the original operator's session and ends the impersonated session. Always available while an impersonation is active; no-op otherwise.

Data model

A user record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`id`	integer	Primary key. Stable across edits.
`email`	string	Unique. Used as the login identifier.
`name`	string	Display name. Not unique.
`password_hash`	string	Salted hash. Never exposed in read responses.
`role`	enum	One of the configured role slugs. See Permissions below.
`status`	enum	`active`, `inactive` (soft-deleted), or `pending`.
`phone`	string	Optional.
`avatar_url`	string	Optional. Resolves against the Media library.
`locale`	string	Optional. Falls back to site default.
`last_login_at`	timestamp	Updated on successful authentication.
`created_at`	timestamp	Set on create, immutable.
`updated_at`	timestamp	Touched on any edit.

Soft-delete semantics: status = inactive is the soft-deleted state. Soft-deleted records retain all other fields. Permanent delete removes the row entirely.

Authored content attribution: posts, pages, media records, and form submissions store the authoring user's id. When a user is permanently deleted, those references are rewritten to the fallback system account, not to NULL.

USER RECORD├── id integer primary key├── email string unique, login id├── name string display├── password_hash string salted, never returned in reads├── role enum configured role slug├── status enum active | inactive | pending├── profile fields phone, avatar_url, locale└── timestamps last_login_at, created_at, updated_at↓ on permanent deleteFALLBACK SYSTEM ACCOUNT(configured in Settings → General)receives all re-attributed content

Permissions

Access to the Users surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Users surface.

Layer 2 — per-action capability. Within SG-Admin, each Users action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:

Capability	Administrator	Editor	Viewer
List users	✔	✔	✔
Create user	✔	—	—
Edit any user	✔	—	—
Edit own profile	✔	✔	✔
Change own password	✔	✔	✔
Change other user's password	✔	—	—
Soft delete	✔	—	—
Restore	✔	—	—
Permanent delete	✔	—	—
Switch to user	✔	—	—
Switch back (when impersonating)	✔	✔	✔

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Self-protection rules. An operator cannot soft-delete their own account, cannot remove their own administrator role if they are the last administrator on the site, and cannot impersonate themselves. The surface returns a structured rejection in each case.

Audit. Every write — create, edit, password change, delete, restore, impersonation entry, impersonation exit — emits an Activity Log entry. The log records the acting operator, the target record, and the change shape (field-level diff for edits). Activity Log retention is governed by the site's general settings.

REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ last-admin / self-delete /│ │ self-impersonate → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry

Related references

Settings — Reference. Owns the role definitions, the fallback system account, password complexity rules, and Activity Log retention. Changes there reshape the Users permission map.
Tools — Reference. The Switch-to-user impersonation entry points are listed in the user list view, but the impersonation history view and the audit-log search live under Tools.
Pages — Reference. Author attribution on page records points to the user id.
Posts — Reference. Same — post author attribution and the fallback re-attribution rule.
Media — Reference. Media uploads carry an uploader id. Re-attribution applies on permanent delete.
Forms — Reference. Form submission records carry the recipient operator's id when routed to a named user.

For the corresponding customer-facing walkthrough — adding users, assigning roles, recovering a locked-out account — see the Users section of the customer docs at /docs/users.

On this page

Guides

Reference

Changelog

Roadmap