The `api key` must match a key in the database table `apikeys`. The `action` specifies the type of request. Other arguments may or may not be needed, depending on the `action` specified. See the table below for valid actions and parameters.
If the request is not well-formed (missing required arguments, invalid credentials, or invalid action), the API will send a 4xx HTTP code and some plain text, such as `"400 Bad Request"`, `"403 Unauthorized"`, or `"404 Action not defined"`.
| `ping` | None | Used to check if the server is online and responding. Responds with `{"status":"OK"}`.
| `auth` | `username`, `password` | Returns a status of `OK` if the user/pass combination are valid and allowed to login, otherwise returns `ERROR`. Also includes a `msg` with an error or success message.
| `userinfo` | `username` or `uid` | If the username or UID exist in the system, returns the user's profile data in the `data` field. <br>Response format:<br><code>"data":{<br> "uid": "123",<br> "username": "jdoe",<br> "name": "John Doe",<br> "email": "jdoe@example.com",<br> "phone": {<br> 1: "1234567890",<br> 2: ""<br> },<br> "pin": false/true<br>}</code>
| `userexists` | `username` | Returns a field `exists` which is true if the username exists or false if it does not. <br>Example response: `{"status":"OK", "exists":true}`
| `hastotp` | `username` | Returns a field `otp` which is true if the user has 2-factor authentication setup or false if the user does not.
| `verifytotp` | `username`, `code` | Checks if the given TOTP code is valid for the given user at the current time. Returns with `{"status":"OK","valid":true}` or `{"status":"ERROR","msg":"<error message>","valid":false}`.
| `acctstatus` | `username` | Returns the account status in field `account` for the given username. Statuses are `NORMAL`, `LOCKED_OR_DISABLED`, `CHANGE_PASSWORD` (if password expired), `TERMINATED`, or `ALERT_ON_ACCESS` (like `NORMAL` except an alert email is sent to the system admin on successful login).
| `login` | `username`, `password` | Simulates a system login, processing the account status, sending login alerts if needed, and noting a successful login in the security log. Returns a `status` of `OK` if it worked (with `"alert": true` if an admin alert was sent), or a `status` of `ERROR` if anything prevented a successful login.
| `ismanagerof` | `manager`, `employee`, `uid` (optional) | Returns a boolean `managerof` which is true if `manager` is a manager of `employee` or false otherwise. If argument `uid` is present and equal to `1`, `manager` and `employee` will be treated as UIDs, else as usernames.
| `getmanaged` | `uid` or `username`, `get` (optional) | Returns an array of UIDs (or usernames if `get=username`) in `employees` corresponding to the users the given account is a manager of.
| `usersearch` | `search` | Searches for users with names or usernames containing the `search`. Returns them in `result` as an array. <br>Response format:<br><code>"result":[<br> {<br> "uid":"123",<br> "username":"jdoe",<br> "name":"John Doe"<br> },<br> {<br> "uid":"124",<br> "username":"jadoe",<br> "name":"Jane Doe"<br> }<br>]</code><br>If `search` is less than three characters long, a search will not be attempted and `result` will be an empty array (`[]`). The `result` is also `[]` if no results are found.
| `permission` | `uid` or `username`, `code` | Returns boolean `has_permission` if the given user has the given permission code. A list of valid permission codes are found in the database table `permissions`. Note: if a user has the `ADMIN` permission, this will always return true no matter what code is requested, because the user in question should have enough system access to give themselves the permission if so desired.
|`mobileenabled`| None | Returns a boolean `mobile` to indicate the value of the config setting `MOBILE_ENABLED`.
| `mobilevalid` | `username`, `code` | Returns a boolean `valid` to indicate if the supplied username and mobile code are valid.
| `alertemail` | `username`, `appname` (optional) | Send alert email to system administrator regarding the specified user and application.
| `codelogin` | `code` | Validate one-time code and (if successful) return username, realname, and uid for the user who generated the code. For code generation API, see `/mobile/index.php`
| `listapps` | None | Get the list of configured apps from `settings.php` in `{"apps":{}}`.
| `getusersbygroup` | `gid`, `get` (optional) | Get all the user IDs in the specified group. If `get` equals `username`, return usernames instead of user IDs. If `get` equals `detail`, return `[{username: x, name: y, uid: z, pin: true}]`, where `pin` is true if the user has a PIN set, otherwise false.
| `groupsearch` | `search` | Searches for groups with names containing the `search`. See `usersearch` for result format and more details. The differences are the fields returned (`id` and `name`) and the minimum query length (2 characters).
| `checkpin` | `pin`, `username` or `uid` | Check if the supplied PIN matches the user's PIN. Returns a boolean `pinvalid`. If no PIN is set, returns a `status ERROR`, `pinvalid false`, and `nopinset true`.
| `getnotifications` | `username` or `uid` | Get notifications for the user. When successful, returns an array `notifications` with items similar to: `{"id": 1, "timestamp": "YYYY-MM-DD HH:MM:SS", "title": "text", "content": "text", "url": "text", "seen": false, "sensitive": false}`
| `readnotification` | `username` or `uid`, `id` | Mark the notification identified by the user and notification ID as read. Sets `seen` to `true` in future calls to `getnotifications`, and changes how the notification is displayed in the UI.
| `addnotification` | `username` or `uid`, `title`, `content`, `timestamp` (optional, defaults to current date/time), `url` (optional, defaults to empty string), `sensitive` (optional, defaults to `false`) | Add a notification for the given user with the content.
