# API Documentation The AccountHub API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON. ## Request Structure API URLs are typically of the form `http(s)://accounthub-url/api///?args`. 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. ## Response Structure Responses to well-formed requests will have a `status` field containing the string `OK` or `ERROR`. If `status` is `ERROR`, there will also be a field named `msg` containing a human-readable localized error message suitable for display to the user. If `status` is `OK`, there may or may not be additional fields sent, depending on the `action`. 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"`. ## Actions | Action | Additional Arguments | Description | ------------- | --------------------------------------- | ----------- | `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.
Response format:
"data":{
"uid": "123",
"username": "jdoe",
"name": "John Doe",
"email": "jdoe@example.com",
"phone": {
1: "1234567890",
2: ""
},
"pin": false/true
} | `userexists` | `username` | Returns a field `exists` which is true if the username exists or false if it does not.
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":"","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. | `getmanagers` | `uid` or `username` | Returns an array of UIDs in `managers` corresponding to the users the given account is managed by. | `usersearch` | `search` | Searches for users with names or usernames containing the `search`. Returns them in `result` as an array.
Response format:
"result":[
{
"uid":"123",
"username":"jdoe",
"name":"John Doe"
},
{
"uid":"124",
"username":"jadoe",
"name":"Jane Doe"
}
]
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. | `getgroupsbyuser` | `uid` or `username` | Get a list of groups as `[{"id", "name"}]` the given user (by ID or username) is a member of. | `getgroups` | None | Get a list of all user groups in the database. | `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. | `deletenotification` | `username` or `uid`, `id` | Delete the notification identified by the user and notifiation ID.