Users

Users are the individuals who can sign in to Mainframe's Control Center. Each user has login credentials, an optional linked employee record, one or more roles, and an account status that can be enabled or disabled by an administrator.

The user model

The user model contains all the information about a user account, including their identity, avatar, assigned roles, two-factor authentication status, and account activity.

Properties

Name
id
Type
integer
Description
Unique identifier for the user.
Name
is_super_user
Type
boolean
Description
Whether the user is a super user. Super users bypass normal permission checks.
Name
name
Type
string
Description
The user's full display name.
Name
initials
Type
string
Description
Computed initials derived from the user's name, e.g. "JD".
Name
avatar_thumbnail
Type
string | null
Description
URL to a preview-sized avatar image. Null if no avatar has been uploaded.
Name
avatar_url
Type
string | null
Description
URL to the full-size avatar image. Null if no avatar has been uploaded.
Name
email
Type
string
Description
The user's email address. Must be unique across all users.
Name
username
Type
string
Description
The user's login username. Must be unique across all users.
Name
roles
Type
Role[]
Description
Array of roles assigned to the user. Each role object contains id (uuid), name (string), description (string or null), organization (object or null — the organization the role assignment is scoped to), created_at (ISO 8601), and updated_at (ISO 8601).
Name
two_factor_enabled
Type
boolean
Description
Whether the user has confirmed a two-factor authentication secret.
Name
disabled_at
Type
timestamp | null
Description
Timestamp set when an admin disables the account. Null if the account is active.
Name
last_login_at
Type
timestamp | null
Description
Timestamp of the user's last successful login. Null if the user has never logged in.
Name
created_at
Type
timestamp
Description
Timestamp when the user was created.
Name
updated_at
Type
timestamp
Description
Timestamp when the user was last updated.

GET/users

List all users

This endpoint allows you to retrieve a paginated list of all users. By default, a maximum of 20 users are shown per page. Results are ordered by last_login_at descending, with users who have never logged in listed last.

Query parameters

Name
filter[username]
Type
string
Description
Filter users by username (partial match).
Name
filter[status]
Type
string
Description
Filter by account status. Use active for enabled accounts; any other value returns disabled accounts.
Name
filter[unassigned_employee]
Type
boolean
Description
When true, only return users who have no linked employee record.
Name
filter[search]
Type
string
Description
Search users by name, username, or email.

Request

GET

/users

curl -G https://your-domain.com/api/users \
  -H "Accept: application/json" \
  --cookie "mainframe_session=your-session-cookie" \
  -d "filter[search]=john"

Response

{
  "data": [
    {
      "id": 1,
      "is_super_user": true,
      "name": "John Doe",
      "initials": "JD",
      "avatar_thumbnail": "https://your-domain.com/storage/avatars/1/thumbnail.jpg",
      "avatar_url": "https://your-domain.com/storage/avatars/1/original.jpg",
      "email": "john.doe@example.com",
      "username": "johndoe",
      "roles": [
        {
          "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
          "name": "Administrator",
          "description": "Full access to Control Center",
          "organization": null,
          "created_at": "2026-01-10T14:22:00+00:00",
          "updated_at": "2026-01-10T14:22:00+00:00"
        }
      ],
      "two_factor_enabled": true,
      "disabled_at": null,
      "last_login_at": "2026-07-23T08:30:00+00:00",
      "created_at": "2026-01-10T14:22:00+00:00",
      "updated_at": "2026-07-23T08:30:00+00:00"
    },
    {
      "id": 2,
      "is_super_user": false,
      "name": "Jane Smith",
      "initials": "JS",
      "avatar_thumbnail": null,
      "avatar_url": null,
      "email": "jane.smith@example.com",
      "username": "janesmith",
      "roles": [
        {
          "id": "b2c3d4e5-f6a7-4b6c-9d0e-1f2a3b4c5d6e",
          "name": "Operator",
          "description": null,
          "organization": {
            "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
            "name": "North Branch"
          },
          "created_at": "2026-01-12T09:15:00+00:00",
          "updated_at": "2026-01-12T09:15:00+00:00"
        }
      ],
      "two_factor_enabled": false,
      "disabled_at": null,
      "last_login_at": null,
      "created_at": "2026-01-12T09:15:00+00:00",
      "updated_at": "2026-01-12T09:15:00+00:00"
    }
  ],
  "links": {
    "first": "https://your-domain.com/api/users?page=1",
    "last": "https://your-domain.com/api/users?page=4",
    "prev": null,
    "next": "https://your-domain.com/api/users?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 4,
    "per_page": 20,
    "to": 20,
    "total": 68
  }
}

POST/users

Create a user

This endpoint allows you to create a new user account.

Required attributes

Name
name
Type
string
Description
The user's full name.
Name
username
Type
string
Description
The user's login username. Must be unique.
Name
email
Type
string
Description
The user's email address. Must be a valid email and unique.
Name
password
Type
string
Description
The user's password. Minimum 6 characters. Must be confirmed by also sending password_confirmation.
Name
password_confirmation
Type
string
Description
Confirmation of password. Must match exactly.

Request

POST

/users

curl -X POST https://your-domain.com/api/users \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie" \
  -d '{
    "name": "Robert Johnson",
    "username": "robertjohnson",
    "email": "robert.johnson@example.com",
    "password": "SecurePass123",
    "password_confirmation": "SecurePass123"
  }'

Response

{
  "data": {
    "id": 69,
    "is_super_user": false,
    "name": "Robert Johnson",
    "initials": "RJ",
    "avatar_thumbnail": null,
    "avatar_url": null,
    "email": "robert.johnson@example.com",
    "username": "robertjohnson",
    "roles": [],
    "two_factor_enabled": false,
    "disabled_at": null,
    "last_login_at": null,
    "created_at": "2026-07-24T10:30:00+00:00",
    "updated_at": "2026-07-24T10:30:00+00:00"
  }
}

GET/users/{id}

Get a user

This endpoint allows you to retrieve a single user by their ID.

Path parameters

Name
id
Type
integer
Description
The ID of the user to retrieve.

Request

GET

/users/{id}

curl https://your-domain.com/api/users/1 \
  -H "Accept: application/json" \
  --cookie "mainframe_session=your-session-cookie"

Response

{
  "data": {
    "id": 1,
    "is_super_user": true,
    "name": "John Doe",
    "initials": "JD",
    "avatar_thumbnail": "https://your-domain.com/storage/avatars/1/thumbnail.jpg",
    "avatar_url": "https://your-domain.com/storage/avatars/1/original.jpg",
    "email": "john.doe@example.com",
    "username": "johndoe",
    "roles": [
      {
        "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
        "name": "Administrator",
        "description": "Full access to Control Center",
        "organization": null,
        "created_at": "2026-01-10T14:22:00+00:00",
        "updated_at": "2026-01-10T14:22:00+00:00"
      }
    ],
    "two_factor_enabled": true,
    "disabled_at": null,
    "last_login_at": "2026-07-23T08:30:00+00:00",
    "created_at": "2026-01-10T14:22:00+00:00",
    "updated_at": "2026-07-23T08:30:00+00:00"
  }
}

PUT/users/{id}

Update a user

This endpoint allows you to update an existing user's information. Note that passwords are not updated through this endpoint — use POST /users/{user}/generate_password instead.

Path parameters

Name
id
Type
integer
Description
The ID of the user to update.

Required attributes

Name
name
Type
string
Description
The user's full name.
Name
username
Type
string
Description
The user's login username. Must be unique, ignoring the current user.
Name
email
Type
string
Description
The user's email address. Must be a valid email and unique, ignoring the current user.

Request

PUT

/users/{id}

curl -X PUT https://your-domain.com/api/users/1 \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie" \
  -d '{
    "name": "John Doe",
    "username": "johndoe",
    "email": "john.doe@example.com"
  }'

Response

{
  "data": {
    "id": 1,
    "is_super_user": true,
    "name": "John Doe",
    "initials": "JD",
    "avatar_thumbnail": "https://your-domain.com/storage/avatars/1/thumbnail.jpg",
    "avatar_url": "https://your-domain.com/storage/avatars/1/original.jpg",
    "email": "john.doe@example.com",
    "username": "johndoe",
    "roles": [
      {
        "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
        "name": "Administrator",
        "description": "Full access to Control Center",
        "organization": null,
        "created_at": "2026-01-10T14:22:00+00:00",
        "updated_at": "2026-01-10T14:22:00+00:00"
      }
    ],
    "two_factor_enabled": true,
    "disabled_at": null,
    "last_login_at": "2026-07-23T08:30:00+00:00",
    "created_at": "2026-01-10T14:22:00+00:00",
    "updated_at": "2026-07-24T11:05:00+00:00"
  }
}

DELETE/users/{id}

Delete a user

This endpoint allows you to delete a user account.

Path parameters

Name
id
Type
integer
Description
The ID of the user to delete.

Request

DELETE

/users/{id}

curl -X DELETE https://your-domain.com/api/users/1 \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie"

Response

HTTP/1.1 204 No Content

Other user actions

In addition to standard CRUD, the following endpoints support managing a user's roles, account access, password, and sessions:

POST /api/users/{user}/roles — Assign a role to the user. Body: role_id (required), organization_id (optional, scopes the role assignment to an organization).
PUT /api/users/{user}/roles — Remove a role assignment from the user. Accepts the same body as above.
POST /api/users/{user}/enable — Re-enable a disabled user account, clearing disabled_at.
POST /api/users/{user}/disable — Disable a user account, setting disabled_at.
POST /api/users/{user}/generate_password — Generate and set a new random password for the user.
GET /api/users/{user}/sessions — List the user's active sessions.