PHPackages art-of-wifi/unifi-api-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. art-of-wifi/unifi-api-client ActiveLibrary[HTTP & Networking](/categories/http) art-of-wifi/unifi-api-client ============================ API client class for use with Ubiquiti's UniFi controller v2.2.0(1mo ago)1.3k371.4k↓20.8%240[4 issues](https://github.com/Art-of-WiFi/UniFi-API-client/issues)[1 PRs](https://github.com/Art-of-WiFi/UniFi-API-client/pulls)MITPHPPHP >=7.4.0 Since Sep 5Pushed 1mo ago64 watchersCompare [ Source](https://github.com/Art-of-WiFi/UniFi-API-client)[ Packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client)[ Docs](https://github.com/Art-of-WiFi/UniFi-API-client)[ RSS](/packages/art-of-wifi-unifi-api-client/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)DependenciesVersions (112)Used By (0) UniFi Controller API client class --------------------------------- [](#unifi-controller-api-client-class) [![License](https://camo.githubusercontent.com/96085bd2468245e8430a82671a849f71719cd45d801751eae8e7e329635f5dbb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4172742d6f662d576946692f556e6946692d4150492d636c69656e74)](https://github.com/Art-of-WiFi/UniFi-API-client/blob/main/LICENSE)[![Packagist Version](https://camo.githubusercontent.com/ca6e96e8f91ca118d32c72e5bc37e33d31089af127b750132ef5b801c8c1e5bd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6172742d6f662d776966692f756e6966692d6170692d636c69656e74)](https://packagist.org/packages/art-of-wifi/unifi-api-client)[![Downloads](https://camo.githubusercontent.com/d47d1613bf38a51c43d8a8ef7c93ca7b1b386cd61e7be5d38c5221d22953306c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6172742d6f662d776966692f756e6966692d6170692d636c69656e74)](https://packagist.org/packages/art-of-wifi/unifi-api-client)[![PHP Version](https://camo.githubusercontent.com/bd07983fe27aef5df997965ced8bb16a464882aeb27048404539ded47a4773fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6172742d6f662d776966692f756e6966692d6170692d636c69656e74)](https://packagist.org/packages/art-of-wifi/unifi-api-client) A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API. This class is used by our API Browser tool, which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser). The package can be installed manually or by using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects. See the [installation instructions](#Installation) below for more details. Why use this API client? ------------------------ [](#why-use-this-api-client) - Easy to use: clear docs, comprehensive method coverage, and helpful examples. - Broad coverage: exposes many UniFi endpoints not (yet) available in the official APIs. - Composer-friendly: installable via [Composer](https://getcomposer.org) and works with modern PHP projects. - Lightweight and dependency-free: no external libraries required; uses cURL. - Secure: communicates over TLS and supports optional SSL certificate validation. - Flexible and extensible: includes `custom_api_request()` for calling any API endpoint. - Robust error handling: throws named Exceptions for precise try/catch handling. - Actively maintained: regular updates and compatibility with recent UniFi versions. Supported Versions ------------------ [](#supported-versions) SoftwareVersionsUniFi Network Application/controller5.x, 6.x, 7.x, 8.x, 9.x, 10.x (**10.2.97 is confirmed**)UniFi OS3.x, 4.x, 5.x (**5.1.3 is confirmed**)Requirements ------------ [](#requirements) - a server or desktop with: - PHP **7.4.0** or higher (use version [1.1.83](https://github.com/Art-of-WiFi/UniFi-API-client/releases/tag/v1.1.83)for PHP 7.3.x and lower) - PHP cURL (`php-curl`) module enabled - direct network connectivity between this server/desktop and the host and port where the UniFi Network Application is running (usually TCP port 8443, port 11443 for UniFi OS Server, or port 443 for UniFi OS consoles) - **authentication** — you need one of the following: - an admin **account with local access permissions** as explained here: Do **not** use UniFi Cloud accounts and do not enable MFA/2FA for these accounts. (see [Option 2: Username/Password](#option-2-usernamepassword) below) - **or** an **API key** generated in your UniFi OS console or UniFi OS Server (see [Option 1: API Key](#option-1-api-key-recommended-for-unifi-os) below) - **or** a **Site Manager API key** for routing requests through the Ubiquiti cloud proxy (see [Option 3: Site Manager Proxy](#option-3-site-manager-proxy) below) UniFi OS Support ---------------- [](#unifi-os-support) Starting from version **1.1.47**, this API client also supports UniFi OS-based controllers. These applications/devices/services have been verified to work: - UniFi OS Server, announcement [here](https://blog.ui.com/article/introducing-unifi-os-server) - UniFi Dream Router (UDR) - UniFi Dream Machine (UDM) - UniFi Dream Machine Pro (UDM PRO) - UniFi Cloud Key Gen2 (UCK G2), firmware version 2.0.24 or higher - UniFi Cloud Key Gen2 Plus (UCK G2 Plus), firmware version 2.0.24 or higher - UniFi Express (UX) - UniFi Dream Wall (UDW) - UniFi Cloud Gateway Ultra (UCG-Ultra) - UniFi CloudKey Enterprise (CK-Enterprise) - UniFi Enterprise Fortress Gateway (EFG) - Official UniFi Hosting, details [here](https://help.ui.com/hc/en-us/articles/4415364143511) - HostiFi UniFi Cloud Hosting, details [here](https://hostifi.com/unifi) The API Client automatically detects UniFi OS consoles/servers and adjusts URLs and several functions/methods accordingly. UniFi OS-based consoles require you to connect using port **443** while **8443** which is used for the self-hosted/software-based controllers. When connecting to **UniFi OS Server**, you are required to use port **11443**. ### Remote API access to UniFi OS-based gateways [](#remote-api-access-to-unifi-os-based-gateways) When connecting to a UniFi OS-based gateway through the WAN interface, you need to create a specific firewall rule to allow this. See this blog post on the Art of WiFi website for detailed instructions when using the **"Classic"**firewall: See this blog post when using the **Zone-Based firewall** (ZBF): Upgrading from previous versions -------------------------------- [](#upgrading-from-previous-versions) When upgrading from a version before **2.0.0**, please: - change your code to use the new Exceptions that are thrown by the API Client class - test the client with your code for any breaking changes - make sure you are using [Composer](#composer) to install the API Client because the code is no longer held within a single file - see the note [here](#looking-for-version-1xx) regarding the single file version (1.x.x) of the API client Installation ------------ [](#installation) The preferred installation method is through [Composer](https://getcomposer.org). Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you don't have Composer installed already. Once Composer is installed, execute this command from the shell in your project directory: ``` composer require art-of-wifi/unifi-api-client ``` Or manually add the package to your `composer.json` file: ``` { "require": { "art-of-wifi/unifi-api-client": "^2.0" } } ``` Finally, be sure to include the composer autoloader in your code if your framework doesn't already do this for you: ``` /** * load the class using the composer autoloader */ require_once 'vendor/autoload.php'; ``` Authentication -------------- [](#authentication) The API client supports two authentication methods. Choose the one that fits your setup. ### Option 1: API Key (recommended for UniFi OS) [](#option-1-api-key-recommended-for-unifi-os) API key authentication is **stateless** — no login/logout flow is needed. This is the simplest way to get started with UniFi OS-based controllers. ``` require_once 'vendor/autoload.php'; $unifi_connection = new UniFi_API\Client('', '', 'https://unifi:443', 'default'); $unifi_connection->set_api_key('your-api-key-here'); $results = $unifi_connection->list_alarms(); // no login() needed ``` **How to generate an API key:** 1. Open your UniFi OS console in a browser 2. Navigate to **Integrations** in the sidebar menu 3. Click **Create New API Key** 4. Copy the generated key — it will not be shown again The API key inherits the permissions from the admin user that created it. **Key points:** - API keys are only available on **UniFi OS-based** consoles (UDM, UDR, UCG, UX, UDW, UCG-Ultra, UniFi OS Server, etc.) - No `login()` or `logout()` calls are needed (calling them is harmless and will be ignored) - The client automatically configures itself for UniFi OS when an API key is set ### Option 2: Username/Password [](#option-2-usernamepassword) The traditional authentication method that works with both self-hosted controllers and UniFi OS consoles. ``` require_once 'vendor/autoload.php'; $unifi_connection = new UniFi_API\Client( $controller_user, $controller_password, $controller_url, $site_id ); $login = $unifi_connection->login(); $results = $unifi_connection->list_alarms(); ``` **Requirements for username/password authentication:** - You **must** use a local admin account with **local access permissions** as explained here: - Do **not** use UniFi Cloud accounts - Do **not** enable MFA/2FA on accounts used with this client ### Option 3: Site Manager Proxy [](#option-3-site-manager-proxy) If your console is managed through [unifi.ui.com](https://unifi.ui.com) and you don't have a direct network path to it, you can route API requests through the **Ubiquiti Site Manager cloud proxy**. This uses the [Site Manager API](https://developer.ui.com) connector to reach the console via UI.com's cloud infrastructure. ``` require_once 'vendor/autoload.php'; $client = UniFi_API\Client::connect_via_site_manager( '245A4CA234150000000005F23204000000000638FE970000000061156371:48913759', // console ID 'your-site-manager-api-key', // Site Manager API key 'default' // site (optional) ); // No login() needed — proxy mode is stateless $stats = $client->stat_daily_site(); ``` **Finding the console ID:**The console ID (host ID) is visible in the URL when managing a console via `unifi.ui.com`: ``` https://unifi.ui.com/consoles/{console_id}/network/default/dashboard ``` **Site Manager API key:**Generate a Site Manager API key at under your account settings. This is **not** the same as a local controller API key generated in the UniFi OS console. **Requirements:** - Console firmware version must be >= 5.0.3 - Console must be online and connected to UI.com - For non-organization API keys: limited to the API key owner's consoles only - For organization API keys: can access any console within the organization **You can also enable/disable proxy mode on an existing client instance:** ``` $client = new UniFi_API\Client('', '', 'https://127.0.0.1', 'default'); $client->enable_site_manager_proxy($console_id, $site_manager_api_key); // ... make API calls through the proxy ... $client->disable_site_manager_proxy(); // Client must be re-configured (login, set_api_key, etc.) before making direct calls ``` **SSL verification:**In proxy mode, all requests go to `api.ui.com` which has a valid public CA certificate. SSL peer and host verification is automatically enforced. **Performance note:**Proxied requests add ~800ms of latency compared to direct access due to the cloud hop. Use direct access when available. The proxy is best suited for remote/headless deployments where a direct network path does not exist. **Rate limits:**The Site Manager API enforces rate limits (10,000 requests/minute for v1 stable). When exceeded, the API returns HTTP 429 with a `Retry-After` header. ### When to use which method? [](#when-to-use-which-method) ScenarioMethodController is part of a **UniFi Fabric**API key (**required**)UniFi OS console (UDM, UDR, UCG, etc.)API key (recommended) or username/passwordUniFi OS ServerAPI key (recommended) or username/passwordSelf-hosted Network Application (non-UniFi OS Server)Username/password (API keys are not supported)Remote console via UI.com (no direct network path)Site Manager proxy> **Important:** When your controller is a member of a **UniFi Fabric**, username/password authentication is **not available**. You **must** use API key authentication. UniFi Fabric uses centralized identity management which does not support local login sessions through the API. ### Migrating from username/password to API keys [](#migrating-from-usernamepassword-to-api-keys) If you have existing code using username/password authentication and want to switch to API keys, the changes are minimal: **Before (username/password):** ``` $unifi_connection = new UniFi_API\Client($user, $password, $url, $site_id); $unifi_connection->login(); $results = $unifi_connection->list_alarms(); $unifi_connection->logout(); ``` **After (API key):** ``` $unifi_connection = new UniFi_API\Client('', '', $url, $site_id); $unifi_connection->set_api_key($api_key); $results = $unifi_connection->list_alarms(); ``` **What changes:** 1. Pass empty strings for the `$user` and `$password` constructor parameters 2. Call `set_api_key()` instead of `login()` 3. Remove `logout()` calls (or leave them — they will be silently ignored) 4. In your exception handling, `LoginFailedException` and `LoginRequiredException` will no longer occur; you can keep or remove those catch blocks as you prefer #### IMPORTANT NOTES: [](#important-notes) 1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when managing the site in the UniFi Network Controller. For example, with this URL: `https://:8443/manage/site/jl3z2shm/dashboard` `jl3z2shm` is the short site "name" and the value to assign to $site\_id. 2. The 6th optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate, which is otherwise **disabled** by default. It is **highly recommended** to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller that is associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16. 3. Using an administrator account (`$controller_user` in the above example) with **read-only** permissions can limit visibility on certain collection/object properties. See this [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129) and this [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password isn't visible for **read-only** administrator accounts. ### Code Examples: [](#code-examples) More code examples are available in the [`examples/`](examples/) directory. Exception handling ------------------ [](#exception-handling) The API Client class throws **Exceptions** for various error conditions instead of using PHP's `trigger_error()`function. This allows for more granular error handling in your application code. You can also choose to catch the `UniFi_API\Exceptions\UnifiApiException` Exception to catch all Exceptions that might be thrown by the API Client class. Here is an example of how to catch each of the Exceptions individually: ```