PHPackages                             leonmelis/uq\_free - 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. [API Development](/categories/api)
4. /
5. leonmelis/uq\_free

ActiveLibrary[API Development](/categories/api)

leonmelis/uq\_free
==================

An unofficial PHP implementation for the Ubiqu Free API

1.0.0(7y ago)06MITPHPPHP ^5.6 || ^7.0

Since Jun 1Pushed 6y ago1 watchersCompare

[ Source](https://github.com/LeonMelis/Ubiqu_Free_PHP)[ Packagist](https://packagist.org/packages/leonmelis/uq_free)[ RSS](/packages/leonmelis-uq-free/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Unofficial Ubiqu Free API implementation for PHP
================================================

[](#unofficial-ubiqu-free-api-implementation-for-php)

This is an *unofficial* PHP implementation for the [Ubiqu Free API](https://ubiqu.com/developers). The maintainer of this project is not affiliated with Ubiqu.

License: MIT

Installation
------------

[](#installation)

This library can easily be installed through Composer.

```
composer require leonmelis/uq_free
```

Then use it in your PHP code using:

```
require __DIR__ . '/vendor/autoload.php';

use \LeonMelis\UQ_free;
```

Requirements
------------

[](#requirements)

- PHP >= 5.6 or PHP >= 7.0
- cURL PHP module (`ext-curl`)

NOTE: this library uses `phpseclib` internally. It is recommended (but not required) by phpseclib to have the PHP `ext-openssl` module installed for better performance.

Getting started
---------------

[](#getting-started)

Before getting started, you should have the Ubiqu Authenticate app installed on a mobile device:

- [Apple App store](https://itunes.apple.com/nl/app/authenticate/id934349819)
- [Google Play store](https://play.google.com/store/apps/details?id=com.ubiqu.eid)

Then, create a new `ServiceProvider`:

```
$provider = UQ_free\ServiceProvider::create(
    'My Service Provider',
    'https://mydomain.com',
    'https://mydomain.com/callback'
);

echo "UUID: {$provider->getUuid()}\n";
echo "API key: '{$provider->getAPIKey()}'\n";
echo "Activate admin with nonce: '{$provider->getNonceFormatted()}'\n";
```

The `ServiceProvider` object is now created on the Ubiqu server, but not yet active. To activate the provider (and also become owner of it) use the Authenticate app on your mobile device, choose 'auto-activate' from the settings menu and enter the 9 digit nonce from the `ServiceProvider` object when prompted.

Store the API key and UUID for this provider.

A previously created `ServiceProvider` can be constructed by passing the UUID and API-key to the constructor:

```
$provider = new UQ_free\ServiceProvider($uuid, $api_key);

// Optionally, you can remote fetch the ServiceProvider object
// to get additional data, such as the name.
$provider->fetch();
echo "Using provider {$provider->getName()}\n";
```

Creating assets
---------------

[](#creating-assets)

An `Asset` is created through an `Identification` object. This may be confusing at first, but you have to remember that we don't know the device that will control the asset at this point in time.

The `Identification` object contains a nonce which can be entered in the Authenticate app. Once completed a callback is made from the Ubiqu Free API, notifying us that the identification has been consumed and the asset is ready to use.

```
// To create a new asset
$identification = $provider->createIdentification();
echo "Identify with: '{$identification->getNonceFormatted()}'\n";
// Wait for callback, then we can fetch the asset
$asset = $identification->fetchAsset();
```

Performing an `AssetRequest`
----------------------------

[](#performing-an-assetrequest)

The `AssetRequest` allows to perform a cryptographic method on the private key owned by the end user. This is the heart of the Ubiqu system. The user gets a push-message on their mobile device, asking to approve or reject the request, unlocking their private key using their PIN. Since we have the public key we can validate the signature we receive.

```
/* Authentication */
$authentication_request = $asset->authenticate();
// Wait for callback
$verified = $authentication_request->verify();

/* Sign */
$sign_request = $asset->sign(hash($document));
// Wait for callback
$verified = $sign_request->verify();

/* Decrypt */
$decrypt_request = $asset->decrypt($encrypted_data);
// Wait for callback
$plain = $decrypt_request->getPlainText();
```

Creating a CSR
--------------

[](#creating-a-csr)

It is possible to create a CSR without possession of the private key. However, this is uncommon and requires knowledge of the CSR internal structure (ASN.1). So, a CSR class is added to help you with performing this procedure.

```
$csr = $asset->createCSR(['CommonName' => 'example.com']);
$csr->requestSign();
// Wait for callback
echo $csr->getSigned();
```

Callbacks
---------

[](#callbacks)

Due to the asynchronous nature of the Ubiqu Free protocol (waiting for the user to approve/reject the `AssetRequest` through the app) the Ubiqu Free API makes callbacks to the `callback_url` passed to the API during creation of the `ServiceProvider`. Ubiqu makes a callback every time an object owned by the `ServiceProvider` changes state.

To handle the callbacks, use the `CallbackHandler` class.

```
$handler = new CallbackHandler();
$handler->handleCallback($_POST);
```

The `CallbackHandler` constructor accepts a `CacheInterface` instance for persisting the received updates, of pushing the changes to some data bus.

Caching / persisting
--------------------

[](#caching--persisting)

By default, the `Connector` class uses a `MemoryCache` instance for caching. This prevents having to fetch the same object more than once from the API.

However, the `MemoryCache` is of limited use, due to the very nature of PHP being restarted on each call. Also, this Ubiqu Free library is fairly useless if objects cannot be persisted to something like a database.

To create your own caching/persistence class, all you need to do is implement the `CacheInterface` interface, consisting of 2 simple methods. Pass an instance of that class to the `Connector` constructor.

```
class MyCache implements UQ_free\CacheInterface {
    function read($type, $uuid) {
        return database_read($type, $uuid);
    }

    function write($type, $uuid, $data) {
        database_write($type, $uuid, $data);
    }
}

$connector = new UQ_free\Connector(new MyCache());
$provider = new UQ_free\ServiceProvider($uuid, $api_key, $connector);
```

The data is passed to the writer as a raw `stdClass` as received from the API. The reader is expected to return a `stdClass` instance or an associative array.

You don't necessarily need to store all fields of the `UQObject`instances, or even store every object type.

For all `UQObject` instances you should at least store the UUID and state (`status_code`). For an `Asset` you must also store the value of `public_key`. All other fields are currently not required for the functioning of this library.

More information
----------------

[](#more-information)

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

2899d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/be06b28f711ba19b962a299e003aaffffe27d7f0726baf3911cea87a5d0478a0?d=identicon)[LeonMelis](/maintainers/LeonMelis)

---

Tags

phpapiauthenticateubiquubiqu free

### Embed Badge

![Health badge](/badges/leonmelis-uq-free/health.svg)

```
[![Health](https://phpackages.com/badges/leonmelis-uq-free/health.svg)](https://phpackages.com/packages/leonmelis-uq-free)
```

###  Alternatives

[culqi/culqi-php

Cliente Culqi API para PHP

41356.8k1](/packages/culqi-culqi-php)[comgate/sdk

Comgate PHP SDK

13327.8k](/packages/comgate-sdk)[jstolpe/instagram-graph-api-php-sdk

Instagram Graph API PHP SDK

13998.4k2](/packages/jstolpe-instagram-graph-api-php-sdk)[satispay/gbusiness-api-php-sdk

Satispay GBusiness API PHP SDK

19198.0k4](/packages/satispay-gbusiness-api-php-sdk)[optiosteam/payconiq-client-php

Payconiq API client library for PHP developed by Optios.

1273.4k](/packages/optiosteam-payconiq-client-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)