- Compatible XF 2.x versions
- 2.2
- 2.3
- Additional requirements
- PHP v7.4
- License
- MIT
- Visible branding
- No
API Users creates user accounts that exist only to hold an API key. An API user has no password and no email address, cannot log in, and is not shown to the public as a member.
It is for an administrator who wants a script, a monitor or an integration to act through the REST API as its own account, without that account also being a way into the forum.
A key that acts as a real member is only as safe as that member's account. If the account has a password, it can be guessed, phished or reset by email. If you hand the integration a super user key instead, it can do anything.
An API user is a real, valid account with its own permissions, so a key naming it can do exactly what you allow and nothing else, and there is no other way in to protect.
An API user is recorded as one by this add-on. It is not identified by having no password, so the passwordless accounts XenForo creates itself, for a registration through a connected account, are left alone.
Hiding the account does not hide what it writes. An API user that creates a thread through the API is named on it, like any member.
In the control panel: Setup > API users lists them and has an Add API user button. It needs the new administrator permission Manage API users, which is granted separately from managing users.
From the command line:
Then give it a key. An API user can do nothing until an API key names it. Under Setup > API keys, add a key of type User key with the API user's name.
Either route can also make the account an administrator, for a key that needs to reach the administrative parts of the API. It is given an administrator record holding no permissions; grant the ones it needs under Groups & permissions > Administrators. In the control panel this also needs the Manage administrators permission and your own password, as adding any administrator does.
If you already have an account that was made to be a bot, its edit page offers Actions > Convert to API user.
Converting removes the account's email address and password, and every other way it could log in: connected accounts, passkeys, two-step verification, saved logins and OAuth tokens. It also removes its follows. Its API keys and any administrator record are kept. This cannot be undone.
An account that has been used as a member is refused, and the page says where its content is. Content means anything XenForo would reassign when merging or deleting a user: posts, conversations it started or wrote in, reactions, attachments, media, resources, and whatever an installed add-on registers. Login records, alerts, and a conversation the account was only sent, such as a welcome message, do not count. A banned or unconfirmed account, a moderator, and your own account are refused too.
An API user's edit page carries a notice saying what it is. Its email and password fields are replaced by a note, so neither can be set by accident, and Merge with user is left out of its actions menu.
These changes are for display. The enforcement is on the account itself, so it holds whatever form or add-on tries to set a password or an email address.
Reports whether every API user still has no password and no email address, is hidden, and is able to act, and whether anything has changed an account behind the add-on's back.
Tested on XenForo 2.2.0 Patch 2 and 2.2.19 Patch 2 with PHP 7.4, and on XenForo 2.3.13 with PHP 8.3.
Install the zip through the admin control panel, or unpack it and run:
The add-on creates one table and removes it when uninstalled. It adds no columns to XenForo's own tables.
It has an automated test suite and has been installed, upgraded and uninstalled on the versions above and on several of the author's production forums. Please report anything unexpected in the discussion thread.
It is for an administrator who wants a script, a monitor or an integration to act through the REST API as its own account, without that account also being a way into the forum.
Why not an ordinary account?
A key that acts as a real member is only as safe as that member's account. If the account has a password, it can be guessed, phished or reset by email. If you hand the integration a super user key instead, it can do anything.
An API user is a real, valid account with its own permissions, so a key naming it can do exactly what you allow and nothing else, and there is no other way in to protect.
What an API user is
- It cannot log in. It has its own authentication scheme, which refuses every password.
- It cannot be given a password or an email address. Both are refused wherever they are set: the user edit page, the REST API, a password reset, or another add-on.
- It is not a member to the public. It is left out of the member list, member counts, newest members, statistics and the username autocomplete.
- It has no public profile. Only the account itself and staff who can bypass user privacy can view it.
- It cannot follow anyone or be followed.
- It cannot be merged with another account, in either direction.
- It is still found in the control panel. User search and the username autocomplete both find it, and its edit page is marked.
An API user is recorded as one by this add-on. It is not identified by having no password, so the passwordless accounts XenForo creates itself, for a registration through a connected account, are left alone.
Hiding the account does not hide what it writes. An API user that creates a thread through the API is named on it, like any member.
Creating one
In the control panel: Setup > API users lists them and has an Add API user button. It needs the new administrator permission Manage API users, which is granted separately from managing users.
From the command line:
Bash:
php cmd.php api-users:create "Monitor" --note="what it is for"
php cmd.php api-users:create "Monitor" --admin
php cmd.php api-users:listThen give it a key. An API user can do nothing until an API key names it. Under Setup > API keys, add a key of type User key with the API user's name.
As an administrator
Either route can also make the account an administrator, for a key that needs to reach the administrative parts of the API. It is given an administrator record holding no permissions; grant the ones it needs under Groups & permissions > Administrators. In the control panel this also needs the Manage administrators permission and your own password, as adding any administrator does.
Converting an existing account
If you already have an account that was made to be a bot, its edit page offers Actions > Convert to API user.
Converting removes the account's email address and password, and every other way it could log in: connected accounts, passkeys, two-step verification, saved logins and OAuth tokens. It also removes its follows. Its API keys and any administrator record are kept. This cannot be undone.
An account that has been used as a member is refused, and the page says where its content is. Content means anything XenForo would reassign when merging or deleting a user: posts, conversations it started or wrote in, reactions, attachments, media, resources, and whatever an installed add-on registers. Login records, alerts, and a conversation the account was only sent, such as a welcome message, do not count. A banned or unconfirmed account, a moderator, and your own account are refused too.
On the user edit page
An API user's edit page carries a notice saying what it is. Its email and password fields are replaced by a note, so neither can be set by accident, and Merge with user is left out of its actions menu.
These changes are for display. The enforcement is on the account itself, so it holds whatever form or add-on tries to set a password or an email address.
Checking
Bash:
php cmd.php api-users:validateReports whether every API user still has no password and no email address, is hidden, and is able to act, and whether anything has changed an account behind the add-on's back.
- It exits 0 when everything is fine, and also when there are only warnings.
- It exits 1 when a check fails.
- With
--strict, a warning exits 2, for a monitor that wants to hear of one.
Requirements
- XenForo 2.2.0 or later
- PHP 7.4 or later
Tested on XenForo 2.2.0 Patch 2 and 2.2.19 Patch 2 with PHP 7.4, and on XenForo 2.3.13 with PHP 8.3.
Installation
Install the zip through the admin control panel, or unpack it and run:
Bash:
php cmd.php xf:addon-install Hampel/ApiUsersThe add-on creates one table and removes it when uninstalled. It adds no columns to XenForo's own tables.
Things to know
- An API user cannot be converted back into an ordinary account. Delete it and create a new one.
- A disabled add-on does not guard. While the add-on is disabled an API user still cannot log in, but the user edit form can give it a password. Run
api-users:validateafter enabling it again. - The guards act when XenForo saves an account. A direct database edit or an importer that bypasses XenForo is not refused;
api-users:validatereports the result as a failure. - Uninstalling moves every API user to XenForo's own passwordless scheme. The accounts remain, still unable to log in, but are no longer hidden or guarded: delete any you do not want kept.
- With Archive Site: list each API user in its protected users before archiving.
api-users:validatewarns about any that is missing.
Support
It has an automated test suite and has been installed, upgraded and uninstalled on the versions above and on several of the author's production forums. Please report anything unexpected in the discussion thread.
