Users

List Users

{
    "data": [
        {
            "username": "editor",
            "email": "[email protected]",
            "fullname": "Jane Editor",
            "title": "",
            "state": "enabled",
            "language": "",
            "content_editor": "",
            "access": { "api": { "access": true, "pages": { "read": true, "write": true } } },
            "groups": [],
            "avatar_url": null,
            "twofa_enabled": false,
            "twofa_secret": false,
            "created": "2026-09-01T10:00:00+00:00",
            "modified": "2026-09-01T10:00:00+00:00"
        }
    ],
    "meta": {
        "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
    },
    "links": {
        "self": "/api/v1/users?page=1&per_page=20"
    }
}

Each user row also carries the values of any custom fields the site added to the account blueprint, and an extra map when a plugin supplies column values for it. twofa_secret is a boolean that only says whether a secret has been generated; the secret itself is never returned.

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: it runs after search, and the access and group filters and pagination are applied by the core endpoint after it, so a tab can never widen visibility or change the response envelope. Tabs work with both account backends. With Flex accounts the event's collection is a Flex collection; with plain file accounts it is an ArrayCollection of users keyed by username, and only accounts already in the list are kept from whatever the plugin hands back. 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.

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

Get User

{
    "data": {
        "username": "editor",
        "email": "[email protected]",
        "fullname": "Jane Editor",
        "title": "",
        "state": "enabled",
        "language": "",
        "content_editor": "",
        "access": { "api": { "access": true, "pages": { "read": true, "write": true } } },
        "groups": [],
        "avatar_url": null,
        "twofa_enabled": false,
        "twofa_secret": false,
        "created": "2026-09-01T10:00:00+00:00",
        "modified": "2026-09-01T10:00:00+00:00",
        "twofa_global_enabled": true
    }
}

The response carries an ETag header; send it back as If-Match on Update User to guard against overwriting a concurrent change. twofa_secret only says whether a secret has been generated, and twofa_global_enabled says whether the Login plugin's 2FA support is installed, so a client knows whether to offer 2FA setup. Any custom fields the site added to the account blueprint are included too.

Create User

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

{"data": {"username": "editor", "email": "[email protected]", "fullname": "Jane Editor", "title": "", "state": "enabled", "language": "", "content_editor": "", "access": {}, "groups": [], "avatar_url": null, "twofa_enabled": false, "twofa_secret": false, "created": "2026-09-21T10:00:00+00:00", "modified": "2026-09-21T10:00:00+00:00"}}

Any custom fields the site added to the account blueprint (user/blueprints/user/account.yaml) can be sent in the body too, and are validated against that blueprint.

Update User

{"fullname": "Jane Q. Editor", "password": "N3wSecurePass!"}

{"data": {"username": "editor", "email": "[email protected]", "fullname": "Jane Q. Editor", "title": "", "state": "enabled", "language": "", "content_editor": "", "access": {}, "groups": [], "avatar_url": null, "twofa_enabled": false, "twofa_secret": false, "created": "2026-09-01T10:00:00+00:00", "modified": "2026-09-21T10:00:00+00:00", "twofa_global_enabled": true}}

Supports optimistic concurrency control via the If-Match header. Include the ETag from your last GET request to prevent overwriting concurrent changes.

twofa_enabled and twofa_secret are ignored here, so a client can send back the whole user object without error. Two-factor authentication only changes through the Enable 2FA and Disable 2FA endpoints, which check a code when you change your own account.

Changing the password or setting state to disabled invalidates every API token already issued for the account. Custom fields the site added to the account blueprint can be sent as well.

Delete User

Upload Avatar

{"data": {"username": "admin", "email": "[email protected]", "fullname": "Site Admin", "title": "", "state": "enabled", "language": "", "content_editor": "", "access": {"admin": {"super": true}}, "groups": [], "avatar_url": "/api/v1/thumbnails/3f2a9c1b.jpg", "twofa_enabled": false, "twofa_secret": false, "created": "2026-09-01T10:00:00+00:00", "modified": "2026-09-01T10:00:00+00:00"}}

Delete Avatar

{"data": {"username": "admin", "email": "[email protected]", "fullname": "Site Admin", "title": "", "state": "enabled", "language": "", "content_editor": "", "access": {"admin": {"super": true}}, "groups": [], "avatar_url": null, "twofa_enabled": false, "twofa_secret": false, "created": "2026-09-01T10:00:00+00:00", "modified": "2026-09-01T10:00:00+00:00"}}

Generate 2FA Secret

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

List API Keys

{"data": [{"id": "9f86d081884c7d65", "name": "CI Deploy Key", "prefix": "grav_1a2b3c4...", "scopes": [], "active": true, "created": 1710000000, "last_used": null, "expires": 1717776000}]}

created, last_used and expires are Unix timestamps; expires is null for a key that never expires.

Create API Key

{"name": "CI Deploy Key", "scopes": ["api.pages.read"], "expiry_days": 90}

{"data": {"id": "9f86d081884c7d65", "name": "CI Deploy Key", "prefix": "grav_1a2b3c4...", "scopes": ["api.pages.read"], "active": true, "created": 1710000000, "last_used": null, "expires": 1717776000, "api_key": "grav_1a2b3c4d5e6f..."}}

When the request is authenticated with a scoped API key, the new key must be scoped too, and every scope it asks for must be within the calling key's own scopes.

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.

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

Execute User Row Action

{
    "id": "impersonate-user"
}

{
    "data": {
        "status": "success",
        "message": "Impersonating alice",
        "url": "/admin/impersonate/alice"
    }
}

Post the id of a declared row action. The API confirms the caller may list users (api.users.read), loads the target account (only a super admin may act on a super admin account), and re-checks the action's own authorize — an unknown or unauthorized id is an indistinguishable 404, so nothing leaks. It then fires onApiUserListRowAction with the resolved username; the handler must guard on $event['plugin'], re-authorize against the target, and set $event['result'].

The result is normalized to a fixed shape:

• status — success or error; drives whether Admin2 shows a success or error toast.
• message — optional text shown as a toast (length-capped).
• url — optional redirect. Only a root-relative path (not the protocol-relative //host form) or a same-origin absolute URL survives validation; a javascript:/data: scheme or a cross-origin URL is dropped. Admin2 opens the surviving URL in a new tab with noopener.

A handler that throws degrades to a 200 with status: error and a generic message rather than breaking the Users list; a thrown ForbiddenException propagates as a 403.

See the API Events page for the onApiUserListRowAction contract.

List Groups

{
    "data": [
        {
            "groupname": "editors",
            "readableName": "Editors",
            "description": "Can edit site content",
            "icon": "users",
            "enabled": true,
            "access": { "api": { "access": true, "pages": { "read": true, "write": true } } }
        }
    ],
    "meta": {
        "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
    },
    "links": {
        "self": "/api/v1/groups?page=1&per_page=20"
    }
}

Groups are always read from, and saved to, user/config/groups.yaml. Groups that exist only in an environment overlay are not listed, so every group this endpoint returns can also be edited or deleted.

Get Group

{"data": {"groupname": "editors", "readableName": "Editors", "description": "Can edit site content", "icon": "users", "enabled": true, "access": {"api": {"access": true, "pages": {"read": true, "write": true}}}}}

The response carries an ETag header; send it back as If-Match on Update Group to guard against overwriting a concurrent change.

Create Group

{"groupname": "editors", "readableName": "Editors", "description": "Can edit site content", "access": {"api": {"access": true, "pages": {"read": true, "write": true}}}}

{"data": {"groupname": "editors", "readableName": "Editors", "description": "Can edit site content", "icon": "", "enabled": true, "access": {"api": {"access": true, "pages": {"read": true, "write": true}}}}}

Update Group

{"description": "Can edit and publish site content", "enabled": true}

{"data": {"groupname": "editors", "readableName": "Editors", "description": "Can edit and publish site content", "icon": "users", "enabled": true, "access": {"api": {"access": true, "pages": {"read": true, "write": true}}}}}

Supports optimistic concurrency control via the If-Match header. Include the ETag from your last GET request to prevent overwriting concurrent changes.

Delete Group

Accounts that list the deleted group in their groups keep the entry; it simply no longer grants anything.

List Invitations

{"data": {"invitations": [{"token": "b7c1e0f4a9d2...", "email": "[email protected]", "fullname": "New Editor", "groups": [], "created": 1758448800, "created_by": "admin", "created_by_name": "Site Admin", "expires": 1759053600, "expired": false}]}}

created and expires are Unix timestamps. The access an invitation grants is not included in the listing.

Create Invitation

{"email": "[email protected]", "fullname": "New Editor", "access": {"api": {"access": true, "pages": {"read": true}}}, "expiration": 604800}

{"data": {"token": "b7c1e0f4a9d2...", "email": "[email protected]", "fullname": "New Editor", "groups": [], "created": 1758448800, "created_by": "admin", "created_by_name": "Site Admin", "expires": 1759053600, "expired": false, "link": "https://example.com/admin/invite?token=b7c1e0f4a9d2...", "email_sent": false, "warning": "Email is not configured, so no invitation email was sent. Share the link manually."}}

The invitation is created even when the email can't be sent. In that case email_sent is false and warning explains why, so the link can be shared by hand. The recipient opens the link, and the accept form uses GET /auth/invite/{token} and POST /auth/invite/{token} to create the account.

Revoke Invitation