CloudianOS API Docs

Contents

    Loading contents...

Introduction #

CloudianOS API is a publically available service that we provide for software developers. This document is to list and describe all gateways that you can use to obtain digital information from us. Some services require you to have a valid API key, which can be obtained from here if you have a registered account.

It is possible to access our gateways using client-side scripts, such as AJAX requests, but we recommend you to consider processing crucial information from the server-side (back-end) only.

Here is an example of a CURL function that is used to read the content of a remote document. We utilise this approach in an array of our examples, and we feel confident to recommend this method.

function fetch_api($url, $post = null) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    if(!empty($post)) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
    } 
    $result = curl_exec($ch);
    curl_close($ch);
    return $result;
}

Please report all kinds of flaws and any other concerns to support@cloudianos.com.

genToken #

This gateway is used for generating true random alphanumeric sequences (A-Z, a-z, 0-9) and does not require an API key. For applications with higher privacy standards, we advise utilising tokens that are at least 50 symbols long. The total number of characters to generate should not exceed 100,000,000 (length × size), or the request will be denied with a 413 status. To optimise in terms of performance, we recommend no more than 10,000 to 25,000 characters per single request.

To calculate the amount of combinations based on the length of the string, consider the following formula: 62length. For example, a string with 50 symbols would be 6250 = 4.16470721e89 combinations or that is 4 with 80 zeros after it. Theoretically, it will take 1069 years before a collision occurs.

fetch_api("https://api.cloudianos.com/genToken?length=50&size=1");
URL GET https://api.cloudianos.com/genToken
Params length (Default 50) The length in characters of the key to be generated
size (Default 1) The number of keys to be generated (new-line separated)

auth [Deprecated] #

The gateway auth has been discontinued and is to cease working after December 31, 2019, 23:59 GMT+0. This gateway is no longer supported and will receive no further updates. Please see the following alternative and switch before the termination date.
v2/auth

Request information about the currently logged-in user. Requires API key.

  1. Redirect the user to https://api.cloudianos.com/auth?key=API_KEY&back=RETURN_URL.
  2. If the user is not logged-in into their CloudianOS account, they will be asked to do so.
  3. A page will prompt the user to confirm the permissions requested. If the user denies the permissions, they will be redirected to the &back= URL.
  4. If the confirmation is authorised, a POST request will be executed to the &back= URL, containing the user data.

To read the POST request, consider the following PHP approach.

if (isset($_POST['cloudianos_data'])) {
    $cloudianos_data = json_decode(htmlspecialchars_decode($_POST['cloudianos_data']));
    #echo $cloudianos_data->username
}

Note:

  1. No POST request may be sent to the &back= URL.
  2. The &back= URL and referring URL must both be within the domain to which the API Key belongs.
  3. $cloudianos_data->error will be null unless some error has occurred. Then it will contain an error message.

Login with CloudianOS button

<link rel="stylesheet" href="https://api.cloudianos.com/assets/css/auth-btn.css">
<a href="https://api.cloudianos.com/auth?key=XXXXXX&back=https://cloudianos.com" class="cloudianos-login">Login</a>
URL GET https://api.cloudianos.com/auth
Params key (required, string) A valid CloudianOS API key.
back (required, URL) The URL to which to post the user data.
Demo Auth API demo

v2/auth #

Ask a CloudianOS user for authorisation to retrieve their CloudianOS account information. Requires an API token with permissions for auth or v2/auth. Requires a Private API Key (PAK) associated with your API Key.

How does it work?
  1. You redirect the user to https://api.cloudianos.com/v2/auth?key=API_KEY&back=RETURN_URL.
    1. The user may need to login in their CloudianOS account if they have signed out
    2. A page listing the information you are requesting is prompted.
  2. If the user authorises you to receive the data you requested, they are going to be sent back to the back address (provided in the URL query) with a POST (cloudianos_data) containing a RID (Random ID), or a JSON formatted error (e.g. {"error": "error description"}).
    1. Important! Users with an unconfirmed e-mail or those who are suspended will not be able to generate neither a RID, nor a PID, and instead, an error will be returned via the POST.
    2. If you have not provided a back URL, the RID code will be displayed on the page and the user will be instructed to copy and paste it into your application.
  3. You can exchange a RID code for the users' information by making another (GET) request to the CloudianOS servers. For this request, you will also need a PAK (Private API Key). Therefore, we strongly recommend you sending this request on the back-end to protect your PAK.
    1. A RID code can only be used once.
    2. RID codes expire 5 minutes after they have been generated.
    3. The PAK must be associated with the API key used to generate the RID.
    4. The returned data is JSON encoded (e.g. {"error": null, "username": "...", "email": "..."}). Errors are in the format {"error": "error description"}.
Requesting permissions

(any link pointing to the URL will work)

<link rel="stylesheet" href="https://api.cloudianos.com/assets/css/auth-btn.css">
<a href="https://api.cloudianos.com/v2/auth?key=XXXXXX&back=https://cloudianos.com" class="cloudianos-login">Login</a>
<a href="https://api.cloudianos.com/v2/auth?key=XXXXXX&back=https://cloudianos.com" class="cloudianos-login-light">Login</a>
<a href="https://api.cloudianos.com/v2/auth?key=XXXXXX&back=https://cloudianos.com" class="cloudianos-login-dark">Login</a>
Exchanging a RID

You can use our fetch_api PHP function to retreive the data on the back-end.

fetch_api("https://api.cloudianos.com/v2/auth?retrieve&rid=RID&private_key=PAK");

If you don't receive your RID via the back URL (e.g. if you need the RID in a desktop/mobile application, rather than a website), you can create an input and ask the user to paste the RID. Here's a PHP example:

<form method="post">
    <input type="text" placeholder="Enter your code" name="rid">
    <input type="submit">
</form>

<?php
if (isset($_POST['rid']) && strlen($_POST['rid']) === 50) {
    $data = json_decode(fetch_api("https://api.cloudianos.com/v2/auth?retrieve&rid={$_POST['rid']}&private_key=XXXXXX"));
    #$data->...
}

?>

If you are receiving the RID via the POST, consider something alike the following approach.

$PAK = "XXXXXXXXXXXXXXXXXXXXXXXXX";
if (isset($_POST['cloudianos_data'])) {
    $data = json_decode(fetch_api("https://api.cloudianos.com/v2/auth?retrieve&rid={$_POST['cloudianos_data']}&private_key=$PAK"));
    if ($data['error'] !== null) {
        echo $data['error'];
    }
    else {
        #RID exchanged successfully
        #$data->...
    }
}

The parametres that could be returned after the exchange are:

object(stdClass) {
  ["error"]=>
  "Error description" #NULL or string
  ["username"]=>
  "The username of the user" #string
  ["id"]=>
  "Unique CloudianOS ID (number)" #string
  ["name"]=>
  "Full name of the user" #string
  ["email"]=>
  "Email of the user" #string
  ["registered"]=>
  "DD.MM.YYYY-HH:MM:SS" #string, date and time of account registration
  ["profile_img"]=>
  "URL to profile image file" #string
  ["login_ip"]=>
  "The IP last used to login into CloudianOS" #string
  ["login_loc"]=>
  "City, Country code" #string, the last used location to login into CloudianOS
  ["login_time"]=>
  "DD.MM.YYYY-HH:MM:SS" #string, date and time of last login
}
What is PID?

PID, or also Process ID, is a random token generated (on both the side of the client and on our servers) before the user confirms the permissions, sent to our servers after the user clicks "Authorise" and deleted after the request is complete. This key helps us identify the session and prevents double-submitting or faking an authorisation. If the PIDs on the side of the client and our side don't match, the "Request Permissions" request will be terminated and a warning will be displayed to the user. A RID will not be issued in the case of a PID mismatch.

You may reproduce a PID mismatch situation for testing purposes. You can find instructions here.

Switching from v1 to v2
  1. Update your auth redirection link
  2. The POST query "cloudianos_data" (now plain string instead of JSON) will be your RID
  3. Add a line to make the second API call

With Green: Added characters; Red: Removed Characters

<link rel="stylesheet" href="https://api.cloudianos.com/assets/css/auth-btn.css">
<a href="https://api.cloudianos.com/v2/auth?key=XXXXXX&back=https://cloudianos.com" class="cloudianos-login">Login</a>

<?php
    if (isset($_POST['cloudianos_data'])) {
        $rid = $_POST['cloudianos_data'];
        $cloudianos_data = json_decode(htmlspecialchars_decode($_POST['cloudianos_data']));
        $cloudianos_data = json_decode(fetch_api("https://api.cloudianos.com/v2/auth?retrieve&rid=$rid&private_key=XXXXXX"));

        #echo $cloudianos_data->username
    }
?>
Popout v2/auth

This option is useful if you want to log the user in without reloading/leaving the page. This method is faster than the traditional one and is recommended for applications that value speed. Please note that the data that you receive via JavaScript cannot be trusted. Always authenticate the user on the back-end. Demo

Caution

Your API Key is safe to be present on the client-side. Unauthorised parties may attempt to utilise your API key to obtain a RID, but they will not be able to exchange them unless they have your PAK.

Your RID key is not considered sensitive information, although it is indeed a most important part of the authentification process, for it cannot be exchanged for data without your PAK and is to expire 5 minutes after it has been generated.

However, if you believe your PAK has been compromised, we ask you to immediately contact support@cloudianos.com and we can suspend your old key and give you a new PAK. In the wrong hands, your PAK may be utilised to extract information from CloudianOS users by people impersonating you, your application or your organisation. Exposing your PAK is a violation of our agreement.

Request Permissions URL GET https://api.cloudianos.com/v2/auth
Params key (required, string) A valid CloudianOS API key.
back (URL) The URL to which the RID will be posted and the user redirected.
Demo Demo
Exchange RID URL POST https://api.cloudianos.com/v2/auth?retrieve
Params rid (required, string) A valid RID key.
private_key (required, string) A valid PAK associated with the API Key used to generate the RID.
Demo Demo

Alternative URLs #

You can easily redirect a user to any CloudianOS service by using our customised short URLs. All URL hashes and POST requests are be preserved and submitted to the target.

Specific URLs

These URLs are pointing to fixed documents and are updated when this document is moved or deleted. Visitors are counted and their browsing behaviour is analysed anonymously.

URL Target description
cldn.pro/terms CloudianOS Terms of Use
cldn.pro/privacy CloudianOS Privacy Policy
Profile URLs

This type of URLs can redirect you to your profile or another user's public profile page.

URL Target description
p.cldn.pro Your CloudianOS Profile (must be logged in)
p.cldn.pro/{USER_ID} The Profile Page of {USER_ID}
GO URLs

A short alias to any document on our domain and subdomains. GET requests are transferred.

URL Target description
go.cldn.pro CloudianOS Home Page
go.cldn.pro/{path} www.cloudianos.com/{path}
go.cldn.pro/_s/{subdomain} {subdomain}.cloudianos.com
go.cldn.pro/_s/{subdomain}/{path} {subdomain}.cloudianos.com/{path}
Base domain https://cldn.pro
Subdomains https://go.cldn.pro
https://p.cldn.pro
Register Custom Link Create