Heads up! This is the documentation for v0.2.2, which will soon be deprecated. The current version is 0.3.0 - check out the updated documentation here.
This page is incomplete.

Backend AJAX API

These are pages which accept a POST or GET request (usually via AJAX), perform some action, and then return a response in the form of a JSON object. All backend api pages are stored in the api directory. Success, error, and warning messages are sent to the alert stream, and can be accessed via api/user_alerts.php.

Activates a newly registered user account, using the activation token that was emailed to the user upon account registration or user's user_id (id column in users).

Login required: no

GET request

Variable nameDescription
[token]The user's activation token, as generated during account registration or after a resend activation request.
[user_id]The user's id. Used for admins to bypass the activation token and directly activate a user's account.
ajaxModeSet to true if the request is via ajax, false otherwise.

GET response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • ACCOUNT_INVALID_USER_ID : Invalid user_id specified.
  • ACCOUNT_TOKEN_NOT_FOUND : Invalid token specified.
  • SQL_ERROR : Database error.
  • ACCOUNT_ACTIVATION_COMPLETE : Account successfully activated.
  • ACCOUNT_MANUALLY_ACTIVATED : Manual account activation successful.
  • Authorization failed

Adds a new action-permit mapping for a user or group.

Login required: yes

POST request

Variable nameDescription
action_nameThe name of the secure action to be added for the specified user/group.
permitA string of permit validators, joined by &.
[group_id]If specified, the action-permit mapping will be added for this group.
[user_id]If specified, the action-permit mapping will be added for this user.
ajaxModeSet to true if the request is via ajax, false otherwise.

POST response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • Invalid user_id specified.
  • Invalid token specified.
  • SQL_ERROR : Database error.
  • Invalid action specified.
  • Invalid permit(s) specified.
  • Authorization failed

Create a new group.

Login required: yes

POST request

Variable nameDescription
group_nameThe name of the new group.
home_page_idThe id of the page (as specified in the pages database table) to use as the group's home page.
ajaxModeSet to true if the request is via ajax, false otherwise.

POST response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • PERMISSION_NAME_IN_USE : Group name already in use.
  • PERMISSION_CHAR_LIMIT : Group name too short/long.
  • PERMISSION_CREATION_SUCCESSFUL : Group successfully created.
  • SQL_ERROR : Database error.
  • Authorization failed

Create a new user.

Login required: sometimes

This page can be accessed in admin or registration mode. If accessed in admin mode, authorization for the createUser secure function will be required, and the session CSRF token must be supplied. Otherwise, a new user account can be self-registered if registration is enabled in the site settings. In registration mode, all default groups will be added for the new user. Will fail if the root account has not yet been created.

POST request

Variable nameDescription
user_nameThe username of the new user. Must be between 1 and 25 characters long, letters and numbers only (no whitespace)
display_nameThe display name of the new user. Could be used, for example, to store a user's real name. Must be between 1 and 50 characters long.
emailThe user's email address. Required for sending activation and password recovery emails. Must be between 1 and 150 characters and a valid email format.
[title]The new user's title. Can only be specified in admin mode. In registration mode, the default title for new users (in site settings) will be used for the user's title. Must be between 1 and 150 characters long.
passwordThe password for the new user. Must be between 8 and 50 characters.
passwordcThe password for the new user. Must match the `password` field.
[admin]If specified and set to true, will put the request through in admin mode.
[add_groups]A comma-separated string of group_id's to be associated with the new user. Will only be accepted in admin mode.
[csrf_token]The csrf token for the user's session. In admin mode, must be set or the request will automatically fail.
[skip_activation]If set to true, will skip the activation step for the new user account. Will only be recognized in admin mode.
[primary_group_id]The group_id of the primary group for the new user. Will only be recognized in admin mode.
[captcha]The captcha code displayed on the registration form. In registration mode, must be specified and correctly match the registration captcha or else the request will automatically fail.
ajaxModeSet to true if the request is via ajax, false otherwise.

POST response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • ACCOUNT_USER_CHAR_LIMIT : Username too short/long.
  • ACCOUNT_USER_INVALID_CHARACTERS : Username must be letters and numbers only.
  • ACCOUNT_USERNAME_IN_USE : Username already in use.
  • ACCOUNT_DISPLAY_CHAR_LIMIT : Display name too short/long.
  • ACCOUNT_DISPLAYNAME_IN_USE : Display name already in use. TODO: relax this restriction?
  • ACCOUNT_PASS_CHAR_LIMIT : Password too short/long.
  • ACCOUNT_PASS_MISMATCH : password and passwordc do not match.
  • ACCOUNT_INVALID_EMAIL : Email is not a valid email address format.
  • ACCOUNT_EMAIL_IN_USE : Email address already in use.
  • MAIL_ERROR : Error sending activation email (if in registration mode).
  • CAPTCHA_FAIL : Captcha did not match. (if in registration mode).
  • ACCOUNT_CREATION_COMPLETE : Successfully completed user account setup.
  • ACCOUNT_REGISTRATION_COMPLETE_TYPE1 : Successfully created user account (no activation required).
  • ACCOUNT_REGISTRATION_COMPLETE_TYPE2 : Successfully created user account (activation required).
  • ACCOUNT_PERMISSION_ADDED : Successfully added user to groups (if in admin mode).
  • NO_DATA : No request data was received by the script.
  • SQL_ERROR : Database error.
  • Authorization failed

Delete an action-permit mapping for a user or group.

Login required: yes

POST request

Variable nameDescription
typeThe type of action-permit to delete. Must be set to either user or group.
action_idThe id of the action-permit to delete (in either the user_action_permits or group_action_permits table).
ajaxModeSet to true if the request is via ajax, false otherwise.

POST response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • SQL_ERROR : Database error.
  • Invalid type specified.
  • Invalid action id specified.
  • Successfully deleted action-permit mapping.
  • Authorization failed

Delete a group. Groups which have their can_delete field in the database set to 0 cannot be deleted. This is useful for certain default groups, such as users and admins.

Login required: yes

POST request

Variable nameDescription
group_idThe id of the group to delete (in the groups table).
ajaxModeSet to true if the request is via ajax, false otherwise.

POST response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • SQL_ERROR : Database error.
  • CANNOT_DELETE_PERMISSION_GROUP : Group is not deletable (can_delete=0).
  • Invalid group id specified.
  • PERMISSION_DELETION_SUCCESSFUL_NAME : Group successfully deleted.
  • Authorization failed

Permanently delete a user account. To temporarily disable a user account instead, use the update_user.php api with enabled set to false. Note also that the root account cannot be deleted.

Login required: yes

POST request

Variable nameDescription
user_idThe id of the user to delete (in the users table).
ajaxModeSet to true if the request is via ajax, false otherwise.

POST response

Variable nameDescription
errors[]the number of errors generated by the request.
successes[]the number of successes generated by the request.

Possible alerts generated

  • SQL_ERROR : Database error.
  • ACCOUNT_DELETE_MASTER : The root account cannot be deleted.
  • Invalid user id specified.
  • ACCOUNT_DELETIONS_SUCCESSFUL : User account successfully deleted.
  • Authorization failed

Load a list of action-permits for one or more user(s) or group(s).

Login required: yes

AJAX only: yes

GET request

Variable nameDescription
[user_id]If specified, loads a list of action-permits for the specified user.
[group_id]If specified, loads a list of action-permits for the specified group.
[all]If set to users, loads a list of action-permits for all users. If set to groups, loads a list of action-permits for all groups. Must be specified if neither user_id nor group_id is specified.
[pretty]If set to true, will output the resulting JSON object in a formatted and indented display.

GET response

Variable nameDescription
JSON arrayIf all is specified, an array of objects representing groups and their associated action-permit mappings will be returned. Each group will look something like the following code block. Note that action_permits contains the array of action-permit mappings for the group. Each action-permit mapping, in turn, contains the action name and an object containing associated permits. Each permit, finally, consists of the permit validator name and an array of associated parameters.
{
    "group_id": 1,
    "name": "User",
    "action_permits": [
        {
            "action_id": 3,
            "action": "loadUser",
            "permits": {
                "isLoggedInUser": [
                    "user_id"
                ]
            }
        },
        {
            "action_id": 1,
            "action": "updateUserEmail",
            "permits": {
                "isLoggedInUser": [
                    "user_id"
                ]
            }
        },
        ...
    ]
}
        
If a user_id or group_id is specified, an array of action-permit objects will be returned. In this mode, the permit strings will not be parsed out into their constituent validator functions.
[
	{
		"id": 3,
		"group_id": 1,
		"action": "loadUser",
		"permits": "isLoggedInUser(user_id)"
	},
	{
		"id": 4,
		"group_id": 1,
		"action": "loadUserGroups",
		"permits": "isLoggedInUser(user_id)"
	},
    ...
]
        
[errors[]]the number of errors generated by the request, if it failed.

Possible alerts generated

  • SQL_ERROR : Database error.
  • user_id, group_id, or all must be specified.
  • Invalid user_id, group_id, or all value specified.
  • Authorization failed

Load the currently logged-in user's information.

Login required: yes

AJAX only: yes

GET request

No parameters

GET response

A JSON object containing the following fields for the user's account:

Variable nameDescription
user_idThe id of the currently logged in user.
user_nameThe username of the currently logged in user.
display_nameThe display name of the currently logged in user.
titleThe title of the currently logged in user.
emailThe email address of the currently logged in user.
sign_up_stampThe UNIX timestamp (seconds since Jan 1, 1970) of the time when the currently logged in user's account was created.
last_sign_in_stampThe UNIX timestamp (seconds since Jan 1, 1970) of the time when the currently logged in user's last logged in.
active1 if the user's account is active, 0 otherwise.
enabled1 if the user's account is enabled, 0 otherwise.
primary_group_idThe group_id of the user's primary group.
csrf_tokenThe currently logged in user's CSRF token.

Possible alerts generated

  • SQL_ERROR : Database error.
  • User is not logged in.