Getting Started

Welcome

Ready to enable your app?

KnetikCloud is THE engine that provides a complete backend-as-a-service for your games and apps.

Start using our REST APIs immediately by using your dedicated API URL

https://app_url

You can also start setting up your data by visiting your control panel at
https://admin_url

Coding KnetikCloud Clients

Log in to your control panel and create a client key. A client key will allow your application to authenticate with KnetikCloud.
  • Use a public client for apps which might expose the keys. Public clients don't require a secret to be provided.
  • Use the password grant type when your users authenticate directly with KnetikCloud, client credentials for server-to-server communications
  • If you chose the client credentials grant type, you need to assign a role to your client. You can use an existing one or create on with limited permissions

You can now connect using the chosen authentication method as described in the authentication section

KnetikCloud uses a standard stateless REST interface over HTTPS. Detailed API specifications are provided by Swagger UI. You can also use the Swagger specifications in JSON format at the following URL to automatically import all the KnetikCloud endpoints into Postman or generate your own SDKs using the Swagger CodeGen project.

https://app_url/swagger-doc
				

Your First Request

The following example requests a list of countries by calling one of the public endpoint (hence the abscence of an authentication token)

Curl
curl -X GET --header 'Accept: application/json' 'http://app_url/location/countries'
Request URL
http://app_url/location/countries
Request Headers
{
  "Accept": "application/json"
}
Response Body
[
  {
    "name": "Afghanistan",
    "iso2": "AF",
    "iso3": "AFG"
  },
  {
    "name": "Albania",
    "iso2": "AL",
    "iso3": "ALB"
  },
  ...
]
Response Code
200
Response Headers
{
  "pragma": "no-cache",
  "date": "Thu, 23 Feb 2017 04:02:44 GMT",
  "x-content-type-options": "nosniff",
  "content-type": "application/json;charset=UTF-8",
  "cache-control": "no-cache, no-store, max-age=0, must-revalidate",
  "content-length": "11608",
  "x-xss-protection": "1; mode=block",
  "x-application-context": "KnetikCloud:remote",
  "expires": "0"
}
				

API breakdown

Within Swagger UI, endpoints are organized in modules and resources. A resource is an object exchange between the client and the server, usually a concrete object like a User or a Challenge. We try to keep related resources close together in the documentation.

Each line can be expanded to reveal the module endpoints, typically a series of CRUD operations using (POST, GET, PUT, DELETE respectively), on the specific modules resource(s). Some additional endpoints might be available for non-standard operations.

Authentication

Generating a OAUTH 2 token

Most KnetikCloud endpoints require authentication to protect sensitive information. The API specification documents the permissions needed to access each endpoint in the Required Permissions section of the later.

Security at the transport layer is provided by Oauth 2.0 with the following grant types:

  • Password grant: Used for user authentication, usually from an unsecured web or mobile client when a fully authenticated user account is required to perform actions. ex:
    POST /oauth/token?grant_type=password&client_id=web&username=jdoe&password=68a4sd3sd
  • Client credentials grant: Used for server authentication or secured clients when then secret key cannot be discovered. This kind of grant is typically used for administrative tasks on the application itself or to access other user's account information.
    POST /oauth/token grant_type=client_credentials&client_id=server-client-id&client_secret=1s31dfas65d4f3sa651c3s54f

The endpoint will return a response containing the authentication token as follows:
{
	"access_token":"25a0659c-6f4a-40bd-950e-0ba4af7acf0f",
	"token_type":"bearer",
	"expires_in":2145660769,
	"scope":"write read"
}

Using the OAUTH 2 token

Use the token obtained in the previous step in subsequent request headers to authenticate (see below).
Authorization Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOj...

PASSWORD GRANT TOKENS ARE SHORT LIVED: When using public clients (password grant type mostly), you will need to implement some logic to automatically refresh your token before it expires to avoid having to re-authenticate

Social Authentication

You can allow users to log into your site using their Facebook or Google+ accounts. We can either generate a new basic account with some information pulled from the other site, or you can link them to an existing user account and provide a new way for them to log in.

The details of how to obtain access differ based on which social media site they are going though, but once obtained both work in a similar way through KnetikCloud.

Facebook

Configuring Account and Apps

Log into Facebook and create an app if you have not already. See their site and documentations for up-to-date details on how to do this: https://developers.facebook.com/docs/apps.

Log into the your KnetikCloud admin and head to the "Security Management" -> "API Keys" section (or clieck here). Either create a new API Key or select the one you are already using in your site/app and edit it. To enable facebook, you just need to add "facebook" to the Add Social Auth section.

Additionally, while you are in the admin, you can head to the "Platform Management" -> "Configurations" section (or click here) and check the setting of "social_login_auto_create". A value of "true" indicates that if a user logs in with an unrecognized facebook account that a new KnetikCloud account should be created for them automatically. Set this to "false" if you only want to log in users that have been previously registered and have linked their accounts directly (see below).

Get a User Logged in

Follow Facebook's current instructions on using their api in whichever language you are working in to retrieve a user access token. Docs currently found here: https://developers.facebook.com/docs/facebook-login/access-tokens#usertokens.

Once you have obtained an access token for the user, you can use it to log the user into KnetikCloud. Retrieving such an OAuth token is very similar to the other methods, using grant_type "facebook" and providing the access token from Facebook as a "token" property. Example:

POST /oauth/token?grant_type=facebook&client_id=web&token=dghukaeruhkfsdelubsDhudxv

Using the Token

Once you have obtained a KnetikCloud token using the above instructions, you can treat it like any other OAuth Token. Add it to the header "Authorization" with the prefix "Bearer " to any call to make it on behalf of the user. If the user later logs and and returns, they can log in with their Facebook account again and if they use the same Facebook account, they will be logged into the same KnetikCloud account again.

Linking Accounts

If the user is already logged in to a KnetikCloud account and wants to link their Facebook account for future login, you can simply follow the instructions above to obtain an access token for Facebook and then, rather than call the oauth endpoint to log in, use the existing KnetikCloud token to call to the Facebook linking endpoint, passing it the Facebook access token.
CURL example

curl -X POST \
  https://app_url/social/facebook/users \
  -H 'authorization: Bearer XXXCURRENTKNETIKCLOUDTOKENXXXX' \
  -H 'content-type: application/json' \
  -d '{
	"access_token":"XXXXXXXXFACEBOOKACCESSTOKENXXXXXXXXX"
}'
Request URL
https://app_url/social/facebook/users
Request Headers
{
  "Accept": "application/json",
  "authorization" "Bearer XXXCURRENTKNETIKCLOUDTOKENXXXX""
}
Request Body
{
	"access_token":"XXXXXXXXFACEBOOKACCESSTOKENXXXXXXXXX"
}
Response Code
202

If successful, the user can log in using their Facebook account as described above and the resulting KnetkCloud token will be linked to this account, rather than a new account. The call will fail if the Facebook token is invalid or if the associated Facebook account it already linked to another user. If the current KnetikCloud user was already linked to another Facebook account, that link will be replaced.

Google

Configuring Account and Apps

Log into the google API Console and create a project if you have not already. See their site and documentations for up-to-date details on how to do this: https://developers.google.com/identity/sign-in/web/devconsole-project.

Log into the your KnetikCloud admin and head to the "Security Management" -> "API Keys" section (or clieck here). Either create a new API Key or select the one you are already using in your site/app and edit it. To enable google, you just need to add "google" to the Add Social Auth section.

Additionally, while you are in the admin, you head to the "Platform Management" -> "Configurations" section (or click here) and set the following configs.

  • social.google.client_id - From your Google OAuth client
  • social.google.secret_key - From your Google OAuth client
  • social.google.redirect_url - The redirect url registered with Google

You can also check the setting of "social_login_auto_create". A value of "true" indicates that if a user logs in with an unrecognized google account that a new KnetikCloud account should be created for them automatically. Set this to "false" if you only want to log in users that have been previously registered and have linked their accounts directly (see below).

Get a User Logged in

Follow Google's current instructions on using their api in whichever language you are working in to retrieve an authorization token. Docs currently found here: https://developers.google.com/identity/sign-in/web/server-side-flow.

Once you have obtained an authorization token for the user, you can use it to log the user into KnetikCloud. Retrieving such an OAuth token is very similar to the other methods, using grant_type "google" and providing the access token from Google as a "token" property. Example:

POST /oauth/token?grant_type=google&client_id=web&token=dghukaeruhkfsdelubsDhudxv

Using the Token

Once you have obtained a KnetikCloud token using the above instructions, you can treat it like any other OAuth Token. Add it to the header "Authorization" with the prefix "Bearer " to any call to make it on behalf of the user. If the user later logs and and returns, they can log in with their Google account again and if they use the same Google account, they will be logged into the same KnetikCloud account again.

Linking Accounts

If the user is already logged in to a KnetikCloud account and wants to link their Google account for future login, you can simply follow the instructions above to obtain an authorization token for Google and then, rather than call the oauth endpoint to log in, use the existing KnetikCloud token to call to the Google linking endpoint, passing it the Google authorization token.
CURL example

curl -X POST \
  https://app_url/social/google/users \
  -H 'authorization: Bearer XXXCURRENTKNETIKCLOUDTOKENXXXX' \
  -H 'content-type: application/json' \
  -d '{
	"access_token":"XXXXXXXXGOOGLEAUTHORIZATIONTOKENXXXXXXXXX"
}'
Request URL
https://app_url/social/google/users
Request Headers
{
  "Accept": "application/json",
  "authorization" "Bearer XXXCURRENTKNETIKCLOUDTOKENXXXX""
}
Request Body
{
	"authorization_code":"XXXXXXXXGOOGLEAUTHORIZATIONTOKENXXXXXXXXX"
}
Response Code
202

If successful, the user can log in using their Google account as described above and the resulting KnetkCloud token will be linked to this account, rather than a new account. The call will fail if the Google token is invalid or if the associated Google account it already linked to another user. If the current KnetikCloud user was already linked to another Google account, that link will be replaced.

Tools

Postman for Development

We strongly recommend using Postman to test your REST calls directly. Postman allows for a direct import of Swagger JSON specifications and will create all the collections on your behalf, ready to use. You can get sample data from Swagger UI to copy/paste in the body of the Postman request.

SDKs

KnetikCloud provides a number of REST wrappers to use with your favorite language and library. The SDKs conveniently provide all the request and response objects (resources) used by the various endpoints.

You can also generate your own SDKs and customize them by using the Swagger JSON specification document and the Swagger CodeGen project.

You can troubleshoot API calls and results by consulting Use error codes & descriptions


Security

KnetikCLoud security schema is based on roles and permissions. As you've read in the authentication section, users and clients are assigned roles. These roles contain any number of permissions as defined by an administrator of the app.

Default Roles & Permissions

While some endpoints don't require authentication, most operations require a minimum set of permissions to protect the integrity of your data. Following the standard CRUD paradigm, access to resources is provided by CRUD endpoints using the appropriate HTTP methods that can be arranged in 2 groups: operations that read resources, and operations that modify resources. Typically the former (GET) will be protected by a *_USER permission while the later will require a *_ADMIN permission.

KnetikCloud comes loaded with 2 useful roles. You can retrieve a list of roles by using the GET /security/roles endpoint.

  • ROLE_USER: assigned to all registered users by default, granted most *_READ permissions, except for endpoints that might compromise privacy or the integrity of the application (logs, rule engine, etc). This role is locked which means it cannot be deleted or modified.
  • ROLE_ADMIN: Similarly to ROLE_USER, this role is granted ALL *_ADMIN permissions by default, and is the role of the default admin account provided during registration. It also contains all the *_READ permissions of the system. This role is locked.

Custom Roles

If the default roles are too broad for you, you always have the ability to create your own role in the control panel. Once you created you roles, you can assign it permissions as long as you own these permissions yourself.

The custom roles are especially useful to limit access to the control panel sections and associated admin endpoints. You might want to create a separate role for each specific department heads with only access to their data.

Warning: Some permissions have dependencies in the control panel because a few sections require READ access to other modules to present choices.

Custom Permissions

You can also create your own permissions that can be granted to custom roles if you want to control access to your own data. The admin control panel provides a simple UI to do just that. These permissions can be used for example on the client side to build adaptive UIs.

KnetikCloud will have no way to enforce these permissions because it doesn't know the rules to apply to them.

Configuration Module

This module manages loosely formatted key/value pairs that can be used to store application-wide settings or module specific or 3rd party configuration information.

Security

Configuration key/value pairs are private by default. A lot of the built-in configuration items contain 3rd party keys that you wouldn't want your users to see or modify. Public keys on the other hand can be seen by users but can only be modified by admins (users who's role was granted the CONFIGS_ADMIN permission, admin user by default). Private keys can only be seen and updated by admins.

Built-in configuration

The system requires a certain number of configuration items to be set properly in order to function as expected. These are settings provided by 3rd party APIs such as payment gateways and messaging services. You will find a definition of these configuration items in their respective owner module documentation. You can also retrieve a list of all the configuration items and their description using the GET /configs endpoint.

The other class of configuration items are more similar to rules that can be applied to fine tune the system to you specific needs. Example of that include enforcing unique emails, or setting the naming convention for invoices, etc

Custom Configuration

Since the configuration items are simple key/value pairs, you can also use it to store your own application settings such as asset locations, preferences, etc. Although we don't provide any format, we do not recommend storing large amount of data in JSON format for example, because this module is not designed to handle large values. Using JSON is acceptable for storing smaller datasets such as images metadata (name, size, with, etc) or copyright information (company, year, etc).

The system doesn't provide any mechanism to validate configuration values for custom properties.

Expanding Resources

Although KnetikCloud tries to provide a number of default fields for resources that we deem interesting, we certainly cannot cover all the needs of all applications. Most clients will want to store resource metadata specific to their context. We provide a powerful framework to allow you to define such data and build dynamic forms on the client through the use of additional properties.

Additional Property Types

  • Files: A generic type to indicate a property is a file asset so it can be displayed accordingly by the client. It includes common file properties such as size and type.
    • Images: simply specifies that the property should be displayed as an image
    • Videos: simply specifies that the property should be displayed as an image
    • Audio: simply specifies that the property should be displayed as an image
    • Files Group: a list of files that are logically related to each other such as multiple resolution for an image
  • Text: A loose text field that can be used to store anything from a simple word to a structured document. ALthough we don't recommend using this type to store large values, it can be leverage to store JSON data with a small number of keys
    • Formatted Text: A subtype of text that simply marks the value as being formatted. This property doesn't enforce any formatting, it merely gives an indication to the client on how to display the text properly, for example in a WISYWIG editor.
  • Numbers
  • Booleans
  • Dates: Enforces the value of the property ot be a Unix Timestamp. useful to display the property as a calendar.

Resource Templates

Some resource in KnetikCloud can be associated with templates. A template defines how resources should be created in the context of your application and applies validation to your resource values.

Creating Templates

The control panel provides screens for resources that support templates.

Template Features

  • Enforce additional properties
  • Provide default values
  • Apply validation rules to properties

Users Module

This is the most important module in the KnetikCloud eco-system. A lot of different modules leverage it to associate resources with authenticated users, although not strictly required. It provides a lot of powerful features needed in most online games and applications.

Supported Features:

  • Additional Properties
  • Templates

Endpoint

/users

Registration

For users to be authenticated and access protected endpoints, they must first be registered in the system. If you already have your own user management system, you will still need to create user accounts in KnetikCloud and pair them with your own, as described in the next section.

You can register users by calling the POST /users endpoint. This is one of the few POST endpoints that are actually public and cannot be blocked at the time of writing. This means users can call this endpoint directly from the client (browser for example) without requiring any credential of any sort.

The user resource is pretty self explanatory, and supports additional properties to augment the default ones. There is only a minimun information required, only the necessary properties to enable authentication and uniquely identify accounts

Default vs custom role

By default, the system provides a rule to automatically assign ROLE_USER to newly created users. This can be overwritten by updating the BRE rule in the control panel and specifying your own ROLE. The rule can also be disabled to allow for account verification for example. In this case you will need to create an additional rule to assign the desired role with your own conditions.

You can also assign a role directly in the control panel. Admin users by default will need to register as regular users, and be upgraded by a peer. This could be automated by building a custom rule that look for a secret key in one of the user's additional properties.

Linking your own users

If you manage your own users, you will be required to declare them to KnetikCloud if you want them to do anything useful in our system. The easiest way to do this is to register the users with KnetikCloud at the same time as you're registering them in your system and copy the KnetikCloud user ID in your own database for future reference.

Store Module

Behaviors

Behaviors are business rules that apply specifically to store items. Behaviors are enforced during different phases of an item lifecycle (checkout, fulfillment, usage, etc).

While items can have multiple behaviors applied to them, it's possible that two or more behaviors conflict and would prevent an process to complete successfully, use with caution.

  • Consumable
  • Expireable
  • Fulfillable
  • GuestPlayable
  • LimitedGettable
  • PreReqEntitlement
  • Spendable
  • TimePeriodGettable
  • TimePeriodUsable

Subscriptions

Features Supported

  • Additional Properties
  • Templates

KnetikCloud handles recurring payments and entitlements associated with subscriptions. We support several models to cover most needs:

  • Consolidated billing
  • ...

Concepts

  • Subscription: A subscription is essentially a store item which SKUs map to payment plans. A subscription item is typically fulfillable to the user's inventory to facilitate tracking entitlements (whether or not a subscription payment is up-to-date).
  • Subscription Plan: A plan is a payment schedule and a set of rules that describe how subscriptions start, expire, renew, etc. In particular each plan requires 4 SKUs corresponding to various life cycle phases:
    • Primary SKU: is the SKU that is used when purchasing the subscription initially. It can be used to offer lower introductory prices
    • Recurring SKU: is the SKU that is used to determine the recurring charges amount. It is also the SKU stored in the user's inventory and used to verify entitltment.
    • Late Payment SKU: is used when a payment is posted past the expiration period (late fee), optionally
    • Re-activation SKU: is used when a payment is posted past the grace period (re-activation fee), optionally
    At the minimum a plan defines
    • when a subscription will be billed the first time
    • the recurring charges period
    • how many times we should try charging the account before giving up (maxBillAttempts)
    • how long to wait before terminating a subscription (billGraceDays).
    A few other settings you might be interested too:
    • maximum terms: the maximum number of times a subscription can be renewed
    • trial offers: allows you to automatically move people to another plan beyond the max number of terms. Useful for trial offers
    • minimum terms: minimum number of terms to charge an account
    • bill consolidation: charge every accounts at the same date

Payment Flow

  • Initial Purchase: follows the normal checkout flow
    1. Create a cart and add the subscription primary SKU
    2. Generate an invoice for the cart
    3. Pay the invoice
    4. Wait for payment confirmation (!) (!!)
    5. ...
    6. >>>Item added to user's inventory, subscription started
  • (!) Make sure the payment gateway provides in return a payment method token that can later be used for reccurring charges. Depending on the provider, this setting can be turned on globally or per transaction.
    (!!) Some payment gateways don't provided a tokenized payment method (). These integrations will not work for subscription since Knetik will not be saving credit card information to charge it again
  • Recurring Charges

    Subscriptions are charged on the basis of the selected plan, either at the end of the term based on the initial subscription purchase date or at a specific date for a pro-rated price when using consolidated billing plans.

    At the time of billing, an new invoice is automatically generated and a payment request is sent to the payment gateway. Once we receive the payment confirmation, the subscription is automatically renewed. To be notified of subscription status changes, you will need to create a BRE rule that listens for that specific event subscription_status_change. You can for example, forward the notification to a URL on your server with the Forward Event Action, or give away an item, or whatever else you see fit.

    All of these interactions happen in the background, but you will see the movement of invoices in your control panel, and various reports are available to monitor your rebill statistics.

Comment Service

The comment service allows you to enable your users to provide comment and feedback on any object or topic in your system that you wish. Comments are targeted using a "context" which is the type of object the comment is about (video, user, etc) and "context_id" which is the unique identifier for the specific object. The object being described does not need to exist within KnetikCloud and thus the "context" and "context_id" can be whatever you want, including things that exist only within your application itself.

New Comment

A user can create a comment with a simple call to the KnetikCloud API. The comment will be attributed to the user whose OAuth Token is used to make the call. If using a "client_credential" token to make the call from a server, the user field will be left null for later.
CURL example

curl -X POST \
  https://app_url/comments \
  -H 'authorization: Bearer XXXCURRENTKNETIKCLOUDTOKENXXXX' \
  -H 'content-type: application/json' \
  -d '{
	"context": "video",
	"context_id": "37",
	"content": "This video was very funny, but I hated it anyways!"
}'
Request URL
https://app_url/comments
Request Headers
{
  "Accept": "application/json",
  "authorization" "Bearer XXXCURRENTKNETIKCLOUDTOKENXXXX""
}
Request Body
{
	"context": "video",
	"context_id": "37",
	"content": "This video was very funny, but I hated it anyways!"
}
Response Code
200
Response Body
{
	"id": 1246453,
	"context": "video",
	"context_id": "37",
	"content": "This video was very funny, but I hated it anyways!",
	"summary": "This video was very funny, but I",
	"created_date": 1500297679,
	"updated_date": 1500297679,
	"user": {
		"id": 686721,
		"username": "Bob12465",
		"display_name": "BobTheCommentor",
		"avatar_url": "http://i.imgur.com/1LmDmct.jpg"
	}
}

Displaying Comments

When displaying an object that may have comments on it, you can retrieve them using the following endpoint.
CURL example

curl -X GET \
  'https://app_url/comments?context=video&context_id=37&page=1&size=25&order=created_date:ASC'
Request URL
https://app_url/comments
Request Params
context=video&context_id=37&page=1&size=25&order=created_date:DESC
Response Code
200
Response Body

{
  "content": [
	{
	  "id": 1246453,
	  "context": "video",
	  "context_id": "37",
	  "content": "This video was very funny, but I hated it anyways!",
	  "summary": "This video was very funny, but I",
	  "created_date": 1500297679,
	  "updated_date": 1500297679,
	  "user": {
	    "id": 686721,
	    "username": "Bob12465",
	    "display_name": "BobTheCommentor",
	    "avatar_url": "http://i.imgur.com/1LmDmct.jpg"
	  }
	}
  ],
  "last": true,
  "total_pages": 1,
  "total_elements": 1,
  "first": true,
  "sort": null,
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

This example returns the first 25 comments, listing the newest first. The query parameters for pagination and sorting are standard throughout KnetikCloud, as is the response format which lists the total number of items, the page returned, whether there are pages before or after this one, etc.

Other controls

Comments can also be edited and deleted by the original commenter or admins. See full API documentation for details.