Users

List Users

List User Tabs

{
    "data": {
        "tabs": [
            { "id": "all", "plugin": "api", "label": "All Users" },
            { "id": "active", "plugin": "my-plugin", "label": "Active", "icon": "fa-bolt", "priority": 10 }
        ],
        "defaultFilter": "all",
        "showAll": true
    }
}

The response data is an object with three keys:

• tabs — the ordered tab row. Each tab carries an id (sent back as ?filter=<id>; all is reserved for the built-in tab), a plugin slug, and a plain-text label. Tabs may also include icon, priority (higher sorts earlier), and badge / badgeEndpoint for a live count.
• defaultFilter — the tab the client should open on when no filter is present in the URL. Defaults to all; a plugin can nominate another tab via $event['defaultFilter'] (it is honoured only when it maps to a tab the caller can see, otherwise it falls back to the first tab).
• showAll — whether the built-in "All Users" tab is present. It is true by default; a plugin can set $event['showAll'] = false to drop it when showing every account isn't a useful (or safe) landing view. "All Users" is only dropped once the plugin has contributed at least one authorized tab, so the row is never empty.

A plugin filter can only narrow the listing: search, the caller's permission scope, and pagination are all applied by the core endpoint after the plugin's filter runs, so a tab can never widen visibility or change the response envelope. See the API Events page for the onApiUserListFilters and onApiUserListFilter contracts.

List User Columns

{
    "data": {
        "columns": [
            {
                "id": "my-plugin-valid-till",
                "plugin": "my-plugin",
                "label": "Valid until",
                "field": "subscription.valid_till",
                "formatter": "datetime",
                "sortable": false,
                "priority": 50
            }
        ]
    }
}

The response data.columns is the ordered list of plugin-declared columns. Each column carries:

• id — unique column id.
• plugin — the owning plugin slug.
• label — the plain-text column header.
• field — the key to read from each user's extra map on GET /users.
• formatter — one of text, link, date, datetime, boolean, number, badge. The server validates this against the whitelist and falls back to text for anything else; the client renders it, so no markup or renderer crosses the wire.
• sortable — optional; whether the column offers a client-side sort of the current page.
• priority — optional; higher sorts earlier.

Columns are plugin-owned but safe by construction: the values in each user's extra map are scalars only, an authorize check is re-run server-side (and stripped from this response), and the data event is isolated so a misbehaving plugin degrades to missing values rather than breaking the listing. Column values are resolved only for the accounts on the current page — never for every account. Like the filter tabs, columns require the Flex-accounts backend.

See the API Events page for the onApiUserListColumns and onApiUserListColumnData contracts.

Get User

Create User

{"username": "editor", "password": "SecurePass123!", "email": "[email protected]", "fullname": "Jane Editor"}

Update User

Delete User

Upload Avatar

{"data": {"username": "admin", "email": "[email protected]", "avatar": {"name": "admin-a1b2c3d4.jpg", "type": "image/jpeg"}}}

Delete Avatar

Generate 2FA Secret

{"data": {"secret": "JBSW Y3DP EHPK 3PXP", "qr_code": "data:image/png;base64,..."}}

List API Keys

{"data": [{"id": "abc123", "name": "CI Deploy Key", "scopes": [], "created": 1710000000}]}

Create API Key

{"name": "CI Deploy Key", "scopes": [], "expiry_days": 90}

{"data": {"id": "abc123", "name": "CI Deploy Key", "api_key": "grav_...", "scopes": [], "created": 1710000000}}

Revoke API Key

Enable 2FA

{"code": "123456"}

{"data": {"twofa_enabled": true}}

Disable 2FA

{"code": "123456"}

{"data": {"twofa_enabled": false}}

List User Row Actions

{
    "data": {
        "actions": [
            {
                "id": "impersonate-user",
                "plugin": "impersonate",
                "label": "Impersonate",
                "icon": "fa-user-secret",
                "action": "start",
                "confirm": "Impersonate this user?",
                "priority": 80
            }
        ]
    }
}

The response data.actions is the ordered list of plugin-declared row actions. Each action carries:

• id — unique action id; the key posted to the execution endpoint.
• plugin — the owning plugin slug.
• label — the plain-text button label (also its accessible name and tooltip).
• icon — optional Font Awesome icon class.
• action — optional verb passed back to the handler; opaque to the client.
• confirm — optional prompt shown in a confirmation dialog before the action runs.
• priority — optional; higher sorts earlier.

Actions are plugin-owned but safe by construction: no markup or renderer crosses the wire, the list is capped, and the authorize check is re-run server-side and stripped from this response. The authorize on a declaration gates only which buttons render — it is not a security boundary; the execution endpoint re-authorizes independently. Like the filter tabs and columns, row actions require the Flex-accounts backend.

See the API Events page for the onApiUserListRowActions and onApiUserListRowAction contracts.