Official sCloud Developer Documentation.          Version: 3.1      Get the SDK

Introduction Last updated: 15-05-2024

1. User authentication and authorizing your app

sCloud uses OAuth 2.0 for API authentication, authorization and to generate access tokens.

Authorization flow
web flow
code flow



Application creation screen:

Below is a screenshot of the app creator screen on the developers dashboard website. Developers dashboard.

Required information needed on the application creation screen:
Application name This is the name of your application that will connect to sCloud's API.
OAuth redirect URI Your application return url must match this, otherwise an error will be thrown, refer to our error list for more information on errors.
Website Your application website describing your app.
Optional Image Add a image that is shown when people connect or authorize your app.
This can optionally be retrieved from your sCloud photo storage account.
Finally a short description about your app. Input a short description about your app.

You can also delete your application from the developers dashboard you can also view, revoke and change your access tokens for your appplication aswell as revoke individual authorized users of your registered application.

OAuth 2.0 Authorization

[OAuth 2.0] Authorize endpoint.
copy
https://scloud.live/OAuth2/authorize
[OAuth 2.0] Authorization
php javascript ajax java
GET https://scloud.live/OAuth2/authorize?client_id={app_key}&scope={scope}
&response_type=code&redirect_uri={redirect_uri}&state={state}


view raw
(GET) PARAMETERS:
client_id The app's key, found in the Developers dashboard..
OAuth redirect URI Where to redirect the user after authorization has completed. This must be the exact URI registered in the Developers Dashboard.
response_type The grant type requested, either token or code.
scope This parameter allows your user to authorize a subset of the scopes selected in the Developers dashboard. Multiple scopes are separated by a space. If this parameter is omitted, our authorization page will request all scopes selected on the Permissions tab. Read about scopes in the OAuth Guide.
state
The state parameter serves two functions. When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect. This gives your app a chance to persist data between the user being directed to sCloud's authorization server and back again, such as using the state parameter as a session key. This may be used to indicate what action in the app to perform after authorization is complete, for example, indicating which of your app’s pages to redirect to after authorization.

The state parameter also serves as a CSRF protection mechanism if it contains a random value per request. When the user is redirected back to your app, double check that the state value matches what you set it to originally. See Sections 4.4.1.8 and 4.4.2.5 of the OAuth 2.0 threat model spec.
1. Example using our SDK
[SDK in php]
php javascript ajax java
Generates a authorization url to sCloud authorization server.$sCloud->generateAuthUrl(1);
view raw

sCloud redirects the user back to the app, sCloud's API will return a (code) response in the return URL. The redirect will include a code in the URL and the original state parameter that you provided on the authorization request..


https://example-app.com/?code=zxaskrDczMzRlNDEwY&state=9dda75bd30

OAuth 2.0 Access Token

Your application will need to receive an access token before it can make API calls this is done via the OAuth 2.0 protocol using the returned code response from the authorizaton request this is then exchanged for a access token.

[OAuth 2.0] Access token endpoint.
copy
https://scloud.live/OAuth2/access_token
[OAuth 2.0] Access token (CURL)
php javascript ajax java

	curl https://scloud.live/OAuth2/access_token \
    -d code=AUTHORIZATION_CODE \
    -d grant_type=authorization_code \
    -d redirect_uri=REDIRECT_URI \
    -d client_id=APP_KEY \
    -d client_secret=APP_SECRET


//CURL headers

    POST /OAuth/token HTTP/1.1
    Host: https://scloud.live/OAuth2/access_token
 
     code=Yzk5ZDczMzRlNDEwY
     &grant_type=code
     &redirect_uri=https://example-app.com/cb
     &client_id=mRkZGFjM
     &client_secret=ZGVmMjMz
     &code_verifier=Th7UHJdLswIYQxwSg29DbK1a_d9o41uNMTRmuH0PM8zyoMAQ
view raw
[OAuth 2.0] Access token (sCloud SDK | php)
SDK php javascript ajax java

 // Exchange the auth code for an access token
  $token = API('token', array(
    'grant_type' => 'authorization_code',
    'client_id' => $SkycloudClientID,
    'client_secret' => $SkycloudClientSecret,
    'redirect_uri' => $baseURL,
    'code' => $_GET['code']
  ));
view raw
(POST) PARAMETERS:
client_id (String) The app's key, found in the Developers dashboard..
OAuth redirect URI (String) Where to redirect the user after authorization has completed. This must be the exact URI registered in the Developers Dashboard.
grant type authorization_code
code The code that was returned in the redirect after a user authorized your application.
client_secret Secret key known only to the application. It is essentially the application’s own password.

Application authorized users. 1.5

Your app retrieves a access token for each authorized user of your application, the access token is the key to connect to the authorized users sCloud account. Each user authorized can instantly revoke access to your application from with in (My sCloud Dashboard) if desired.

API Requests

All API requests need a access token to be able to use the functionallity of the API.

Authorization Url Endpoint

https://scloud.live/OAuth2/authorize

The authorization endpoint is used to request user authorization to the application that you registered in the sCloud developers dashboard.

Access Token Url Endpoint

https://scloud.live/OAuth2/access_token

Used to generate access tokens for your application.

API Basename

https://api.scloud.live

This is the URL basename used to make the API calls to the sCloud API server.

Category: Account

GET /account_info

SDK | php
$sCloud->API('account_info');//json format
//or individual account info
$sCloud->API('account_info')['username'];//json format
[account_info] raw JSON response - example values.
php javascript ajax java
{"storage_used":0,
"username":"skyGodinthecloud24",
"creation_date":"2024-02-18 17:41:32",
"verified":"1",
"account_type":"3",
"email":"user202433-app@scloud.live",
"devices":"5",
"ref_id":"null",
"iso_lang":"en",
"fname":"john",
"lname":"doe"}

//or
{"username":"skyGodinthecloud24"}
view raw
(JSON) RESPONSE PARAMETERS:
storage_used Holds the users storage amount in available bytes.
username holds the username of the authorized account.
fname hold the users first name.
lname holds the users last name.
creation_date holds a timestamp of when the account was created.
verified account verified 0=no 1=yes.
account_type holds the user account type either a 1 for a FREE account or 3 for a PREMIUM account depending on what account type the user holds.
if a 3 is present then there will be other values in the response, this will include premium_start and premium_expire timestamps.
email Holds the users registered (alias) email address, (note this is not the real address but an sCloud issued email id) this helps protect the users email address.
iso_lang ISO language code of registered user.
devices integer of connected device count, you can use the account_devices API Endpoint to retrieve more information on the connected devices.
ref_id returns the referal id if any of the referer service or user..

Category: Account

POST /account_create

(JSON) POST PARAMETERS:
email: valid email address, otherwise. an error may be thrown.
username: create a username for this account.
password: md5() password hash or Plain text.
first_name: first name of new user account.
last_name: last name of new user account.
iso_lang: (OPTIONAL) ISO language code of new user account.
ref_id: (OPTIONAL) referer id usually yourself or your registered application (prefered value).
If not set then the referer id of the Developer/creator of the application will be used by sCloud's API.
SDK | php
$new_account_values=array('email','username','password','first_name','last_name','iso_lang','ref_id');
$sCloud->API('account_create',$new_account_values);//json format
[account_create] raw JSON Object response - example values.
php javascript ajax java
{"username":"kingoftheclouds","created":"1715716412","result":"1","error":"0"}
view raw
(JSON) RESPONSE PARAMETERS:
result if 1 then account was created successfully else if a 0 is present then there was an error creating an account, if so there should also be an error code returned
(refer to our error codes for more information on error codes).
created timestamp of when the account was created.

NOTE: Account verification is required in order to be able to use this newly created account, upon creating an account with this API call (/account_create) sCloud will automatically send an email to the registered email address asking to verify their account.

Category: Account

GET /account_delete

SDK | php
$sCloud->API('account_delete',(delete_token));//json format
[account_delete] raw JSON response.
php javascript ajax java
{ "result":"1"}"
view raw
(JSON) RESPONSE PARAMETERS:
result 1=success, 0=error.

Category: Account

GET /account_devices

(Optional) POST PARAMETERS:
Int Limit the amount of devices to display.
SDK | php
$sCloud->API('account_devices',10);//Limit to just 10 devices
//or
$sCloud->API('account_devices');

//or to get individual values
$sCloud->API('account_devices')['count'];
[account_devices] raw JSON response.
php javascript ajax java
{"result":"1",
"count":10,
"error":0,
"devicename":{
"1":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"2":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"3":"sCloud_app",
"4":"sCloud_app",
"5":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"6":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"7":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"8":"sCloud_app",
"9":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"10":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/124.0.0.0 Safari\/537.36",
"ip":{
"1":"185.238.223.123",
"2":"185.238.223.123",
"3":"185.238.223.123",
"4":"185.238.223.123",
"5":"185.238.223.123",
"6":"185.238.223.123",
"7":"185.238.223.123",
"8":"185.238.223.123",
"9":"185.238.223.123",
"10":"185.238.223.123"}

//or

{"result":"1",
"count":1,
"error":0,
"devicename":{
"1":"sCloud_app",
"ip":{
"1":"185.238.223.123",
}
view raw
(JSON) RESPONSE PARAMETERS:
result 1=data available, 0=no data to display.
count Connected device count.
error 1=success, 0=error.
device_name Device name of the connected device.
ip Ip address of when this device connected/signed in to sCloud

Category: Account

GET /account_refs

SDK | php

$sCloud->API('account_refs');//json format
[account_refs] raw JSON response - example values.
php javascript ajax java
{"result":"1","error":"0","refs":"326"}
view raw
(JSON) RESPONSE PARAMETERS:
result if 1 then data is available else if a 0 is present then no data available meaning no referers yet for this account).
refs int count of referers for the account that is authorized with your application.

Category: Cloud

POST /cloud_archive

POST PARAMETERS:
File file path to archive.
encryption security encryption method (AES-256).
SDK | php
$folder_to_archive="Files/BusinessInvoices";//example path replace with your actusl scloud file path.
$sCloud->API('cloud_archive',$folder_to_archive);
[cloud_archive] raw JSON response - example values.
php javascript ajax java
{"result":"1","error":"0","filename":"examplefile_video.mp4"}
view raw
(JSON) RESPONSE PARAMETERS:
result 1 success, 0 error/failure.
error holds a error code if any.
filename name of the file or files that was successfully uploaded.

Category: Cloud

POST /cloud_audio

POST PARAMETERS:
File file path to archive.
encryption security encryption method (AES-256).
SDK | php
$folder_to_archive="Files/BusinessInvoices";//example path replace with your actusl scloud file path.
$sCloud->API('cloud_archive',$folder_to_archive);
[cloud_archive] raw JSON response - example values.
php javascript ajax java
{"result":"1","error":"0","filename":"examplefile_video.mp4"}
view raw
(JSON) RESPONSE PARAMETERS:
result 1 success, 0 error/failure.
error holds a error code if any.
filename name of the file or files that was successfully uploaded.

Category: Cloud

POST /cloud_download

POST PARAMETERS:
File the file or files that are to be uploaded. Multiple files can also be downloaded in just 1 call. encryption security encryption method (AES-256).
SDK | php
$upload_location="";
$sCloud->API('cloud_upload',$filetoupload,'AES-256',$upload_location);
[cloud_upload] raw JSON response - example values.
php javascript ajax java
{"result":"1","error":"0","filename":"examplefile_video.mp4"}
view raw
(JSON) RESPONSE PARAMETERS:
result 1 success, 0 error/failure.
error holds a error code if any.
filename name of the file or files that was successfully uploaded.

Category: Cloud

POST /cloud_upload

POST PARAMETERS:
File the file or files that are being uploaded. Multiple files can also be uploaded in just 1 call.
encryption security encryption method (AES-256).
type Upload type, (File) or (os) for object storage.
SDK | php
$upload_location="";
$sCloud->API('cloud_upload',$filetoupload,'AES-256',$upload_location);
[cloud_upload] raw JSON response - example values.
php javascript ajax java
{"result":"1","error":"0","filename":"examplefile_video.mp4"}
view raw
(JSON) RESPONSE PARAMETERS:
result 1 success, 0 error/failure.
error holds a error code if any.
filename name of the file or files that was successfully uploaded.

Integrations

Section coming soon..

Section Item 4.1

Section coming soon..

Get started with the (PHP) SDK

Note: a config.php file is being called from within sCloud_SDK.php the config.php file should contain your client_id and app_secret keys aswell as your registered redirect URI that you registered in the developers dashboard.

[simple usage] (php SDK)
SDK php javascript ajax java

<?php
 include 'sCloud_SDK.php';//include skycloud PHP SDK LIBRARY.
 $sCloud = new sCloud( 'app_key_here', 15,2,0 );

 $sCloud->generateAuthUrl(1);
 $token=$sCloud->API('token');//json format
 
 //Example API calls...
//$sCloud->API(GET,POST);
$userInfo=   $sCloud->API('account_info');//json format
$userEmail=  $sCloud->API('account_info')['registered_email'];//json format
$storageUsed=$sCloud->API('account_info')['used_storage'];//json format
$randImage=$sCloud->API('images')['22'];//json format
$sCloud->API('Videos')['count'];
  
$sCloud->AuthToken();//get authentication token info, expiry, creation date
  
   ?>
view raw

Methods:

Generates a authorization url to sCloud authorization server.$sCloud->generateAuthUrl(1);
(Options) Values:
1 will show as a hyperlink with a href tag
0 URL string, with this option set you can change the clickable text by putting the returned URL string in to your own (a href) tag.

Generates a access token from sCloud's access server.$sCloud->API('token');//json format;

API call. Where method is a sCloud API get method, example (account_info) or (Videos) etc...$sCloud->API(METHOD,PARAMS);//OPTIONAL POST PARAMETERS
(Options) Values:
METHOD API Method     
Params (optional) POST parameters.    
(Helper) Methods
Get token information.$sCloud->AuthToken();//get authentication token info, expiry, creation date

Download from github Coming soon.

Download from github Coming soon.

Available error codes with definitions.

200 Indicates that the request has succeeded.
404 Not found.This is by far the most common HTTP status code you can get. It indicates that the URL you used in your request doesn’t exist on the API server, or origin server. While this is a 4XX error, which usually means something on the client-side is wrong, this can also indicate a server problem. Sometimes API URL paths change after a version update, but sometimes they change because something on the server went wrong.
401 Unauthorized This status code means you haven’t yet authenticated against the API. The API doesn’t know who you are and it won’t serve you.
403 The forbidden status indicates that you don’t have permission to request that URL. You’re authenticated, but the user or role you’re authenticated for isn’t permitted to make the API request. This also occurs when you have an authentication issue, like when using the wrong API key or trying to access features your subscription plan doesn’t allow for.