Integration Document

Cloudike PAYG integration documentation provides a comprehensive guide for customers to connect their systems with Cloudike’s platform, enabling seamless authentication, subscription management, and SMS notifications.

Definitions

The main subjects involved in the cross-integrations are described below:

Term	Description
Cloudike PAYG (or Cloudike)	Cloudike PAYG (Pay-As-You-Go) is a universal software platform owned by Cloudike Inc. and hosted on its Amazon AWS account. The platform is designed to launch various projects for different Customers, enabling them to provide cloud services to their end users.
Customer	A company that has contracted with Cloudike Inc. and uses Cloudike PAYG resources to provision its users.
Customer Core System	The Customer Core System (hereafter referred to as Customer's System) is an infrastructure of the specific Customer that is located on the Customer’s hardware resources (i.e., outside of Cloudike PAYG). It can be integrated with Cloudike PAYG’s infrastructure via the Internet.
User	An end user of Cloudike PAYG who belongs to a specific Customer (and hence to a specific Tenant).
Tenant	A tenant is an isolated entity in the Cloudike PAYG platform created for a specific Customer. The concept of a tenant includes: - Private tenant settings (e.g., name, description, logo, project domain, various Customer's System endpoints, etc.) - Customer’s Users - A set of Packages
Package	A product that includes Cloudike's cloud disk quota and can be purchased by Users.
Subscription	A Package that has been activated for a specific User.

---

User Authentication Procedure

We assume that various client applications of the Cloudike PAYG platform (browser, desktop, Android, and iOS clients) will use the same user authentication method. This method will also be the same for all attached tenants.

The first API method is used by clients when the user first launches the client. This API method provides a list of all tenants available to end users on the Platform.

During the first launch, the user must select a Tenant (i.e., project) they wish to register or log into.

• The API method accepts the user's phone number (optional parameter) as input.
• As output, the client responds with a list of tenants recommended for this phone number.
• Recommendation logic can be implemented by analyzing:
  • The phone number's country prefix
  • The source IP address of the requesting client
  • The domain entered by the user in the browser (for web clients)

If no phone number is provided, the method will return an array with all tenants available on the Platform.

The second API method is used to retrieve the public Privacy Policy content of the selected Tenant.
The third API method handles sign-up and sign-in procedures (i.e. specifically for authentication).

Get list of "recommended" Tenants by phone number

GET http://payg.cloudike.com/api/2/tenants/

Input Parameters

Parameter	Type	Required	Description
phone	string	Optional	If provided, the system will return a sublist of a few recommended tenants.

Output

Returns an array of tenants with the following fields:

Field	Type	Description
tenant_name	string	The name of the tenant (i.e., internal ID).
frontend_url	string	A web link to the public frontend.
title	string	A human-readable name of the tenant.
description	string	A brief summary of the project.
logo_url	string	A URL to the tenant's logo.
available_langs	string	A list of languages available for the tenant.

Return Values (HTTP Status Codes)

Code	Description
200 OK	The request was successful.

---

Example Response (JSON)

{
  "_embedded": {
    "tenants": [
      {
        "tenant_name": "star",
        "title": "StarCloud",
        "frontend_url": "https://web.star.cloud/",
        "description": "The solution for backing up your best moments",
        "logo_url": "https://web.star.cloud/assets/logo.svg",
        "available_langs": "en, kz",
        "_links": {
          "self": {
            "href": "http://payg.cloudike.com/api/2/tenants/101/"
          }
        }
      },
      {
        "tenant_name": "ice",
        "title": "IceCloud",
        "frontend_url": "https://www.icebox.com/",
        "description": "The super cold fridge to store your Ice Cream",
        "logo_url": "https://domain.ice/ice-logo.svg",
        "available_langs": "en, id",
        "_links": {
          "self": {
            "href": "http://payg.cloudike.com/api/2/tenants/167/"
          }
        }
      }
    ]
  }
}

Get the "Privacy Policy" Document of the Tenant

GET http://payg.cloudike.com/api/2/offers/

Input Parameters

Parameter	Type	Required	Description
offset	number	No	The starting position of the returned list.
limit	number	No	The number of results to return.
tenant_name	string	Yes	The Tenant’s name.
type	string	Yes	The required offer’s code. Use "privacy_policy".
lang	string	Yes	The language code of the offer (e.g., "en").

API documentation of the method: https://be-saas.cloudike.com/backend_docs/rest/api/2/core_pkg/offers_app/Offers/index.html

Example Request

GET http://payg.cloudike.com/api/2/offers/?offset=0&limit=2&tenant_name=star_cloud&type=privacy_policy&lang=en

Return Values (HTTP Status Codes)

Code	Description
200 OK	The request was successful.

---

Example Response (JSON)

{
  "_links": {
    "self": {
      "href": "http://payg.cloudike.com/api/2/offers/"
    },
    "next": {
      "href": "http://payg.cloudike.com/api/2/offers/?limit=2&offset=2"
    }
  },
  "_embedded": {
    "offers": [
      {
        "created": "2025-02-14T13:01:57.117000+00:00",
        "updated": "2025-02-14T13:01:57.117000+00:00",
        "id": "67af3ec589695ea21a9ef830",
        "tenant_name": "star_cloud",
        "type": "privacy_policy",
        "lang": "en",
        "url": "",
        "_links": {
          "self": {
            "href": "http://payg.cloudike.com/api/2/offers/67af3ec589695ea21a9ef830/"
          },
          "content": {
            "href": "http://payg.cloudike.com/api/2/offers/67af3ec589695ea21a9ef830/content/"
          },
          "offer_view": {
            "href": "http://payg.cloudike.com/offers/67af3ec589695ea21a9ef830"
          }
        }
      }
    ]
  }
}

Notes

The _embedded → offers field contains the array of offers. Each responded offer contains 2 useful fields:

• _links → content contains a link to download the offer content, which is formatted with HTML markup.

  • The URL could be used to insert the content into an HTML page.

• _links → offer_view contains a link to the web frontend’s view page, which would display the offer as a separate HTML page.

Method of User Authentication (Sign-up/Sign-in)

POST http://payg.cloudike.com/api/2/phone_otp_auth_tokens/

Input Parameters

Parameter	Type	Required	Description
longlived	boolean	No	By default False. Set to True to create long-lived tokens for mobile apps.
device_description	string	Yes (if longlived=True)	Description of the device.
tenant_name	string	Yes	The name of the project (tenant).
phone	string	Yes	The user’s phone number.
action	string	Yes	One of "login" or "reg".
password	string	No	User’s password (if applicable).
sms_otp	string	Yes	One-time password (OTP) sent via SMS (e.g., "12345").

---

Output Parameters

Parameter	Type	Description
id	string	ID of the created authentication token.
client_type	string	Type of client.
device_description	string	Taken from the input parameter.
created	string	Timestamp of token creation (ISO 8601 format).
expires	string	Expiration time of the token (ISO 8601 format).
last_activity	string	Time of last account activity (ISO 8601 format).
user_id	number	Cloudike user account unique ID.
tenant_name	string	Tenant where the user’s account belongs.
token	string	Session token (secret).
user_created	boolean	True if a new user account was created during authentication.

---

Return Values (HTTP Codes)

• 201 Created – Token successfully created.

{
  "id": "Z6Mk8BqiYtZ6Ffpd",
  "client_type": "android-client",
  "client_version": "1.2.0",
  "device_description": "Android 10",
  "created": "2025-02-05T08:44:32.229000+00:00",
  "expires": "2025-03-08T08:44:32.229000+00:00",
  "last_activity": null,
  "user_id": 5,
  "tenant_name": "project_123",
  "secret": "Zt0q3CAcQg6OKMZwcGbtAQ",
  "token": "Z6Lk8BqiYtZ6Ffpd:Zt0q3CAcQb6OKMZwcGbtAQ",
  "user_created": false,
  "_links": {
    "self": { "href": "http://payg.cloudike.com/api/2/users/5/Z6Mk8BqiYtZ6Ffpd/" },
    "user": { "href": "http://payg.cloudike.com/api/2/users/5/" },
    "credential": { "href": "http://payg.cloudike.com/api/2/users/5/credentials/67a324ef1aa262d67a15fa4b/" },
    "gd_user_info": { "href": "http://payg.cloudike.com/api/2/users/5/gd_user_info/" }
  }
}

• 422 ValidationError – Incorrect or missing input parameters. Usually requires additional parameters; check the body for specific required fields:
  • input OTP required
  • incorrect OTP was inputted

{
  "code": "ValidationError",
  "description": "The request has wrong parameters.",
  "detail": {
    "sms_otp": "Required",
    "password": "Required"
  }
}

• 429 TooManyIncorrectAttempts – Too many incorrect attempts; temporary block applied. The amount of seconds until the end of blocking is responded to.

HTTP Headers

Retry-After: 59

Response Body

{
  "code": "TooManyIncorrectAttempts",
  "description": "The action could not be performed because there were too many incorrect attempts by the client. Try again after a while.",
  "detail": {
    "retry_after": 59
  }
}

SMS Notifications Sent to the User

We have two options for sending SMS notifications:

1. Customer provides Cloudike PAYG with an endpoint to the standard SMPP protocol interface.
2. Customer implements the REST API as described below.

---

REST API for Sending SMS

POST https://smsgate.customer.com/send-sms

HTTP Headers

• Authorization: Bearer JWT
• Content-type: application/json

Input Parameters

Parameter	Type	Required	Description
msisdn	number	Yes	Recipient's phone number.
message	string	Yes	Message text.

---

Return Codes

HTTP Code	Description
200 OK	Message was successfully sent.
400 Bad Request	Incorrect request format. The platform will not retry the message.
422 Unprocessable Entity	Invalid phone number or message text (too long/invalid). The platform will not retry the message.
429 Too Many Requests	Too many requests were sent. The platform will retry the message later.
5xx Server Errors	SMSGate is temporarily down. The platform will retry the message.

---

Example Request

POST https://smsgate.customer.com/send-sms

HTTP Headers

• Authorization: Bearer JWT
• Content-type: application/json

Request Body

{
  "msisdn": 123456789012,
  "message": "12345 - your secret code to login StarCloud"
}

User Subscriptions Management

Subscription Model and Concepts

Cloudike PAYG platform provides a specific set of packages tailored to each Customer. The tenant’s packages are available for subscription by tenant’s users.

Cloudike’s package model has the following fields:

Field Name	Type	Description
id	string	Unique ID of the package&.
customer_product_id	string	Unique ID of package from Customer’s side.
name	string	Human-readable name of the package.
cost	number	The package’s cost for one period, in the natural number of minor currency units (i.e. “cents”).
cost_scale	number	By default, it is 100. This represents the number of minor currency units (“cents”) in one major currency unit (“dollar”).
currency	string	The currency’s code, from ISO 4217.
size	number	The amount of storage provided by subscription to the user’s quota (in bytes).
duration	number	The number of period_type time periods included in the pre-paid period.
period_type	string	There are four variants: hour, day, month, year.
is_default	boolean	Whether it is the default package or not. The default package can only exist once. If it exists, it is automatically purchased by the system for the user when they get a 0 quota.
is_enabled	boolean	Whether the package is enabled or disabled. The system does not allow users to subscribe to a disabled package.
tenant_name	string	Assigning the package to a specific Customer based on their tenant name.
description	string	An internal brief summary (not visible to end users).

Subscription Rules

Cloudike’s end users initially have a 0 GB disk quota. Users cannot use Cloudike cloud functions with a 0 GB quota. To upload any data to the cloud, a positive disk quota (>0 GB) is required.

Subscription Mechanism

• Packages are required for incremental increases in the user's disk quota.
• Packages can be purchased by users either in Cloudike apps or via MO requests from the Customer’s System.
• A successful package purchase results in an active subscription.
• A user can have either no active subscription or only one active subscription at a time.
  • Users cannot have two or more active subscriptions simultaneously.

Upgrade & Downgrade Subscription Rules

If a user has an active subscription and orders another subscription:

1. If the new subscription has a larger size, Cloudike will activate it, canceling the old subscription immediately.
2. If the new subscription has a smaller or equal size, the system will block the change.

Subscription Cancellation

A User or Customer's System can initiate the cancellation of an active subscription.

• Cancellation means:
  • Auto-prolongation stops.
  • The subscription remains active until the end of the current pre-paid period.
  • Once the pre-paid period expires, the subscription is automatically closed.

Default Package Requirement

• The Customer must provide exactly one package marked as the default package.
• Default package behavior:
  • Automatically purchased for new user accounts.
  • Automatically re-purchased when a user loses their active subscription and their quota drops to 0 GB.
  • Can be free (cost = 0) or paid, depending on Customer preference.

Subscription Approval

• Subscription to any package requires approval from the Customer’s System.
• Unsubscribing does not require approval, but Cloudike notifies the Customer’s system about any such event.

Subscription Renewal

• Cloudike automatically renews active subscriptions based on the pre-paid period interval.
• Cloudike attempts to approve the renewal in the Customer’s System up to six times with 8-hour intervals.
• If renewal fails, the subscription is automatically canceled.

Grace Period & Account Deletion

• If a user’s quota becomes empty for any reason (e.g., insufficient funds to purchase a new package), a 7-day grace period begins.
• During the grace period, Cloudike sends daily SMS notifications about upcoming data and account removal.
• If the user still has no package after 7 days, Cloudike deletes the user account and all associated data.

Customer's System API

User’s Subscription Approval

Cloudike will call the Customer API to approve actions related to user subscriptions, such as:

• Creation of a new subscription
• Renewal (prolongation) of an already active subscription

GET http://customer.com/purchase_package_approve

HTTP Headers

• Authorization: Bearer JWT
• Content-Type: application/json

Input Parameters

Parameter	Type	Description
msisdn	number	User's phone number (MSISDN).
package_id	string	Unique package ID in Cloudike system.
customer_package_id	string	Unique package ID on Customer’s side.
action	string	"create" (new subscription) or "renew" (subscription prolongation).
cost	number	Subscription cost in minor currency units (e.g., cents).
cost_scale	number	Scale factor (default: 100, e.g., cents per dollar).
currency	string	Currency code (ISO 4217 format).
trx_id	string	Unique transaction ID (max length: 100 bytes, UUID v4 recommended).

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
422 Unprocessable Entity	Invalid msisdn, package_id, or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

Cloudike’s Side API

MO Request to Purchase a Package for the User

This is an MO (Mobile Originated) message with a user’s request sent from the Customer’s side to the Cloudike system (as the content provider). The request invokes Cloudike to approve package purchase (by calling the purchase_package_approve() API from the previous section) and create a new subscription for the user.

This method can also be used to create a new user. If no user with such an MSISDN exists in Cloudike, the user will be created upon successful approval of the request.

POST https://payg.cloudike.com/api/2/purchase_package_request

HTTP Headers

• Authorization: Bearer JWT
• Content-Type: application/json

Request Parameters

Parameter	Type	Description
msisdn	number	User's phone number (MSISDN).
package_id	string	Unique package ID in Cloudike system.
action	string	"subscribe" (subscribe to package) or "unsubscribe" (unsubscribe from package).
trx_id	string	Unique transaction ID (max length: 100 bytes, UUID v4 recommended).

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid secret was sent. No retries required.
422 Unprocessable Entity	Invalid msisdn, package_id, or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

Port-out Notification for the User

The Customer’s System should inform Cloudike immediately if the user has performed a port-out action or contract cancellation.

POST https://payg.cloudike.com/api/2/user_portout

HTTP Headers

• Authorization: Bearer JWT
• Content-Type: application/json

Request Parameters

Parameter	Type	Description
msisdn	number	User's phone number (MSISDN).
trx_id	string	Unique transaction ID (max length: 100 bytes, UUID v4 recommended).

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid tenant_name / secret pair sent. No retries required.
422 Unprocessable Entity	Invalid msisdn or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

MSISDN Change Notification

The Customer's System should inform Cloudike immediately when a user changes their MSISDN. The user's active subscription will be automatically transferred to the new MSISDN without requiring re-creation or additional actions.

POST https://payg.cloudike.com/api/2/user_change_msisdn

HTTP Headers

• Authorization: Bearer JWT
• Content-Type: application/json

Request Parameters

Parameter	Type	Description
msisdn	number	New MSISDN value.
old_msisdn	number	Previous (old) MSISDN value.
trx_id	string	Unique transaction ID (max length: 100 bytes, UUUID v4 recommended).

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid tenant_name / secret pair sent. No retries required.
422 Unprocessable Entity	Invalid msisdn/ package_id or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

Get JWT Token to Access a Private API

The Customer’s System should use a JWT token for authentication when making API requests to Cloudike services.
A JWT token is generated using the following API request:

POST https://payg.cloudike.com/api/3/applications/<app_id>/tokens/

HTTP Headers

• Content-Type: application/json

Request Parameters

Parameter	Type	Description
access_key	string	Application's access key.
scope_name	string	Name of the scope (a list of functions the customer is allowed to call).

Response Body

Field	Type	Description
token	string	The generated JWT token.
expires	string	Date-time of token expiration.

Response Codes

HTTP Code	Description
201 Created	Request was successfully accepted, JWT token generated.
400 Bad Request	Incorrect format of request. No retries required.
422 Unprocessable Entity	Invalid access_key or scope_name. No retries required.

User’s Actions Notifications Sent to Customer’s System

Cloudike will notify the Customer's System of various events occurring with the users. Only one callback will be used for this notification.

POST https://customer.com/user_event_notify

HTTP Headers

• Authorization: Bearer JWT
• Content-Type: application/json

Input Parameters

Parameter	Type	Description
created	string	The date and time of the event in ISO-8601 format (e.g., "2025-02-25T08:37:20+00:00").
event	string	The name of the occurred event (see table below).
msisdn	number	The user's MSISDN (mobile number).
user_id	number	Cloudike’s user ID.
parameters	structure	The JSON structure with variable additional parameters depending on the event.

Events

Event	Additional Parameters (JSON)	Description
user_created	{}	The user account was created.
user_removed	{}	The user account with all its data was removed.
subscription_created	{ "package_id": "9999", "customer_package_id": "CLOUD123" }	The user was subscribed to a new subscription.
subscription_renewed	{ "package_id": "9999", "customer_package_id": "CLOUD123" }	The user's active subscription was successfully prolonged.
subscription_canceled	{ "package_id": "9999", "customer_package_id": "CLOUD123" }	The user's active subscription was canceled.
user_quota_exceed_80	{}	The user’s used storage has reached 80% of their available disk quota.
user_quota_exceed_90	{}	The user’s used storage has reached 90% of their available disk quota.
user_quota_exceed_95	{}	The user’s used storage has reached 95% of their available disk quota.
user_quota_exceed_100	{}	The user’s used storage has reached 100% of their available disk quota.
user_quota_zero	{}	The user's disk quota has reached zero, meaning their account is planned to be removed after 7 days.

Return Codes

HTTP Code	Description
200 OK	Event was accepted by the Customer's System.
400 Bad Request	Incorrect format of request. The platform will not re-try the message.
401 Unauthorized	Invalid secret sent. Request was not accepted, no re-tries required.
422 Unprocessable Entity	Invalid msisdn number or other parameters. The platform will not re-try the message.
429 Too Many Requests	Too many requests sent. The platform will re-try the message.
5xx Server Errors	Web service is temporarily broken. The platform will re-try the message.

The response body can be empty, since we won't read or analyze it.

Appendix: the sequence diagrams

User orders a new subscription in client application

MO request to Cloudike to subscribe a user to the package