Overview

The Ubiqu Free API is a REST API with optional callback notifications. Registering with us as a Service Provider (SP) will allow you to make use of the pre-installed Ubiqu-branded Profile for your own secure sign-up and login needs. Ubiqu Free API generates objects unique for these profiles per Service Provider, called Assets.

To show you how easy it is to integrate our system with yours, you can find a short tutorial below on how to authenticate your users. Please refer to the documentation for information on how to store their data encrypted and how to sign data. This will be a tutorial without asynchronous callbacks, again, please refer to the documentation for details on that.

We expect three basic headers in every call, Content-Type, Accept and X-Api-Key. Currently, we only support JSON Content-Type and Accept headers.

Content-Type: application/json
Accept: application/json
X-Api-Key: deadbeefdeadbeefdeadbeefdeadbeef

We support two types of HTTP requests. POST and GET. GET “gets” information about Identification, Asset, Authenticate, and more objects, whereas POST “creates” objects (except for Assets, which are preinstalled on devices). Valid POST and GET calls should then be relatively obvious. Return objects will be the same for both GET and POST (POST is essentially a GET on a newly created object in this case).

Flow

Users can be sent authentication requests if the asset UUID of that user is known. This UUID might have previously become known in the session, because it was stored in a session cookie or because of it being linked some unique identifier. If known, skip to step 3.

Step 1 – Identification

The first step is letting the user identify himself. With a POST request, such an identify request is created, the Identification object. You can then poll for updates on this identification object, or wait for a callbacks (see documentation).

When a user enters the identification nonce on his mobile phone you receive an update on the poll or the call-back.

Request

curl \
-X GET \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'X-Api-Key: deadbeefdeadbeefdeadbeefdeadbeef' \
https://free.ubiqu.com/api/identification?uuid=deadbeefdeadbeefdeadbeefdeadbeef

curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'X-Api-Key: deadbeefdeadbeefdeadbeefdeadbeef' \
-d '{}' \
https://free.ubiqu.com/api/identification
Coming soon..

Response

{
  "result": {
    "uuid": "ce9b7947b4964751af345f58c3435d33",
    "nonce": "194197169",
    "created_at": "2016-04-01T14:44:27.456951+00:00",
    "asset_uuid": null,
    "status_code": 0,
    "updated_at": "2016-04-01T14:44:27.457000+00:00",
    "nonce_formatted": "194 197 169",
    "status_text": "created"
  }
}

Asset_uuid will be null upon first creating the identification. Display nonce_formatted to the user, and once the user has filled it in, the asset_uuid field should be updated with a UUID. If this UUID is known in your system already, it means a user has returned to your website and it should be treated as a simple login attempt and skip to step 3, if the UUID is not yet known, this should be treated as a sign-up attempt (as far as these two flows differ).

Step 2 – Retrieve Asset information

Use a GET request to retrieve all the asset information. Most importantly, these will be the public keys to the RSA key-pairs stored in our Security Module, which should be used to validate signatures.

Request

curl \
-X GET \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: deadbeefdeadbeefdeadbeefdeadbeef' \
https://free.ubiqu.com/api/asset?uuid=deadbeefdeadbeefdeadbeefdeadbeef

Coming soon..

Response

{
  "result": {
    "uuid": "ce9b7947b4964751af345f58c3435d33",
    "updated_at": "2016-04-01T14:00:01.757021+00:00",
    "created_at": "2016-04-01T14:00:01.756925+00:00",
    "status_code": 1,
    "status_text": "active",
    "public_key_sign": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkpwCWxdeWKFz6kY+i29E\nVeR13XsTZrniNa3G1Onv4aZzpv9uCzA+Zo+a9wcmYUbmuGP7NgANPoPE3pmaTTHd\nj+yl1n/Mk82cegkCe5ckZjGaRDKAnOEEwdJ75kcxO64ug4YURt3gcpIHx7gcS6Hu\nABWMYoavKCln9P0/j2JLCcD6ZyPfGnRMjiD8x01xVvveGzArzQaGAFCwvH73ivXv\nfIvKSP5Y8t4vGJuBV67iRFZRLo6lzhQjtlIrXCySDJBd5DGBs44lI6TfZTwn1Plb\nUCTGoRyNBSieRhdo+kKWeGkN8Wv13gDBDe5AfiphM2Hv55+QY/OiRZo1fPp0dTet\nPQIDAQAB\n-----END PUBLIC KEY-----",
    "public_key_decrypt": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvcp3OVUjrZcKTzOgV4ug\nj0ELZS2bgpbTJ+mvrBZEuINzcTgRtov0bE4OGrSFeVQuHHaSZqXkEQCVPSfTHVxL\nfmUYEXnbHTPhu8nHbOcGhzj1UPg8e+F5Y9Wfno2l1pvuKmATaMwLnrLnxINw7NRf\nqI9aiv6AzbcIEOFKnDe4ehbbJootU2PWiCRfmid0wY6nZjbcq2aEeYPo63zCdApi\nGNIgn95q01wxlfFoY7vu+Jh7/35Q1I1uNAptHpIIq9aUStxl3wz5WynZX9562hp8\nzz3s6Kea2evkgD0VtfsPFTIuDktqBG7B/ZWjxN4iIwsnSi/4PDEhXrcvW5upvXBM\njQIDAQAB\n-----END PUBLIC KEY-----",
    "public_key_authenticate": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApdtYbombgNfXJYzgCOSJ\nnfIRccfeZ6AaaT26g4jggMkWVo49blAqSoUUffM342KAy2TpMuP4OPx9qYTd/yAf\ncWvB/RueYKfiQ/r/HC8+mkfLKVU+OFu85mbsE9S/UZSPqEP7t078oYgaLCWBN6op\nG9OM0VZgK6d3i6lmB1QnOP3iWb6xzcHJqy3OY1UYMXhWgBZbEucanpDA46UMPOSK\nWqwjneK9Fca+84jZccjehpvo+ts5o2wnmL1La/WQ7jpc14b6ZYh50ke58nGLue4s\n6VREGjYepTzMcI8r8Z5ymLAz1ZVoQUBlcD2Ou7cgcGIlQ/t/sQxCS60kc3X8Za9c\newIDAQAB\n-----END PUBLIC KEY-----",
  }
}

Step 3 – Authenticate user

Now that the asset UUID is known, we can send an authenticate request to the user’s profile. This is done through POSTing a new authenticate object, and then waiting for status updates through GET polling or callbacks.

Request

curl \
-X GET \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'X-Api-Key: deadbeefdeadbeefdeadbeefdeadbeef' \
https://free.ubiqu.com/api/authenticate?uuid=deadbeefdeadbeefdeadbeefdeadbeef

curl \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'X-Api-Key: deadbeefdeadbeefdeadbeefdeadbeef' \
-d '{"asset_uuid": "deadbeefdeadbeefdeadbeefdeadbeef", "fingerprint":"cafebabecafebabecafebabecafebabecafebabecafebabecafebabecafebabe"}' \
https://free.ubiqu.com/api/authenticate

Coming soon..

Response

{
  "result": {
    "uuid": "cf778ea629054db5b9feaef1d23141d8",
    "status_code": 0,
    "type": "authenticate",
    "status_text": "created",
    "token": "e6f815cca0154f17b471267a0b5bc6ea",
    "otp": "01835850267822849a62e574cffb1976",
    "asset_uuid": "3e2190362e7e4be8a41b9e582528901e",
    "verified": false,
    "signature": null
  }
}

The OTP field is a unique identifier for this current transaction, and can be safely displayed on the website. The user is shown this OTP on the mobile phone as well and should be instructed to see if these two fields match. When the user has accepted the Authenticate request, a GET on the Authenticate object will most importantly return a HEX-encoded RSA signature (after the user has accepted the authenticate request), which can be verified using the PEM-encoded public key associated with the Asset. For convenience sake, we also verify the signature, and put our findings in the “verified” field.

If this flow has been implemented successfully, you can now do away with passwords, and in some cases even usernames, the only thing you need now for authentication is the Ubiqu App!

Note that our free plan is currently in beta. Please drop us a mail at boris@ubiqu.eu for your API key.