AccountHub/docs/Self-Hosting and Development/API Documentation.md

# API Documentation

The AccountHub API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON.  POST requests are strongly recommended over GET for security reasons (i.e. GET request data, including API keys and plaintext passwords, is saved in server logs and browser history with little to no protection).  You should only use GET requests for debugging purposes or if (for some awful reason) it is not possible to use POST for your use case.

## Request Structure

The API is typically located at `http(s)://accounthub-url/api.php`.

All requests to the API must include a `key` argument containing a valid API key.  They must also include an `action`.  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 API key, or invalid `action`), the API will send a 4xx HTTP code and a JSON string, such as `"400 Bad Request"`, `"403 Unauthorized"`, or `"404 Not Found: the requested action is not available."`.

## 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.  <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.
| `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.  <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.
| `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.