API Documentation

Introduction
Welcome to the Enjin API The Enjin Website API is a JSON-RPC service that exposes data from your website in JSON format for creating your own features and website integrations. The API is currently in beta and will be receiving several updates as we come out with them. This being said, please be sure to check this source for any new features or updates as often as possible. If you feel our API is lacking certain features, please feel free to send us suggestions here. To retrieve data from our API, you'll be given a base URL, this is generally "yourwebsite.com/api/v1/api.php". To use SSL, make sure to use https:// instead of http:// (SSL is currently supported on *.enjin.com domains only). In addition to the full URL, some API calls require parameters and some of these parameters may be optional. Every possible parameter will be listed in each specific API section. Some API calls will require your secret API key. This is used to ensure the protection of sensitive data and prevent unknown users from executing certain actions (such as tagging or untagging a user). Your API key is only shown once when it is generated. Please write down the code and make sure your key is not being shared with other individuals. You can generate a new key if needed in your Admin Panel | Settings | API area. Finally, some API calls will also require a module ID, such as the shopping module. To learn where to find this information, please read this section. To get started, read over the following sections. After that, begin reading through some of the API calls. Enabling the API Making Requests Authentication Enabling Developer Mode Obtaining IDs Response Signature Have questions or suggestions? Send us a ticket.
Enable the Enjin API
To enable your API, visit your admin panel / settings / API area. The content on this page includes your base API URL, your secret API key, and the API mode. Ensure that the API mode is set to "Public". The three API modes currently available are public, disabled, and read only.
Public
Using "Public" means that all API functions are active and the authentication methods can be used to retrieve or modify your website data. Usually, this means using your Secret API Key or being logged in to Enjin.
Disabled
Disabled means that the api is off entirely for anyone trying to access it.
Read Only
If the mode is set to "Read Only", the only calls to the API that will work are those that are not modifying data. For example, methods such as Points.get will work, but Points.set will not. Each API section will detail whether or not read-only is available.
Request format
The API uses JSON-RPC which requires a POST request containing a JSON string with a few parameters:
  • "jsonrpc" must be "2.0"
  • "id" is a random integer that will be returned in the API response
  • "params" is an object containing the parameters for each request
  • "method" is the name of the API class and method, for example "Friends.getList"
Example Request
{
	"jsonrpc":"2.0",
	"id":"12345",
	"params":{
		"api_key": "1a2a3a4a5a6a7a8a9a1b2b3b4b5b6b7b8b9b1c2c3c4c5c6c",
		"preset_id": "12345678"
	},
	"method":"Shop.get"
}
API testing tools
Postman is a user-friendly REST client you can use to test API calls. Note: If you are testing the User.login method, Postman will remember your login cookie. If you prefer to only send “clean” requests without cookies, consider using Fiddler (below) which does not store cookies. Fiddler is a free web debugging proxy Finally, you can use the Try It section under each method of this documentation to test your API requests. Fill in the fields and click “Send API Query!” to test any API method.
Authentication
Each API method in the documentation lists the types of authentication available for it:
Secret Key
  • Specify "api_key" in the request params.
  • This uses the global Secret API Key or Custom API Key found in Admin - Settings - API.
Secret API Key Your secret API key is used as a parameter in some API calls to prevent unknown users from retrieving sensitive data or executing actions (such as tagging a user). If the secret API key is required in an API call, it will be listed in the parameters box. The key will only be shown once when it is generated. Make sure to write down the key while you have it. If you happen to lose it, simply generate a new key. If for any reason you need to generate a new key, you can do this in your admin panel, settings, API area. Simply click the "Change" button next to your current API key. Custom API Keys Custom API Keys are available on the Advanced and Ultimate plans and let you limit the types of functions you can access with the key. For example, you might give a developer an API Key that is only allowed to get data from your Shop and add/remove Points from users. Advanced Plan
  • 1 custom key
Ultimate Plan
  • 10 custom keys
Minecraft Key
  • Specify "authkey" in the request params.
  • This uses the Minecraft server key found in Admin - Minecraft - Servers.
  • This method is useful if you are building Enjin extensions to your Minecraft server.
Session
  • Specify "session_id" in the request params.
  • You can obtain a session_id by calling "User.login"
  • Session IDs will only last for a limited amount of time (typically 30 days, but this is not guaranteed) after which you need to call User.login again for a new Session ID.
Cookie
  • A session cookie will need to be present on the web browser / client - this means the user has to be logged in to Enjin on your domain.
No authentication required
  • This API method can be accessed without any authentication or user login required.
Obtaining IDs
There are various methods that require you to specify an ID. This section will provide you with an easy way of obtaining the majority of those IDs. You will need to follow the section "Enabling Developer Mode" in order to view the additional information listed on this page.
User ID
You can acquire the ID of a profile by navigating to the users wall and then selecting the "About Me" tab. From there, you can easily see the user ID associated with the individual.
Module ID
You can acquire the ID of a module by navigating to your website's administrator panel followed by selecting the "Modules" tab. You will see an additional column reading "Module ID" for each module on your website.
Tag ID
You can acquire the ID of a tag by navigating to your website's administrator panel followed by selecting the "Users" tab. Simply edit any custom tag and the ID will be listed in the dialog's title.
Page ID
You can acquire the ID of a page by navigating to your website's administrator panel followed by selecting the "Pages" tab. You can either select the page and see the page ID in the information box at the top of the editor or you can select the "Page List" sub-tab to view a list of all pages and their IDs.
Minecraft Server ID
You can acquire the ID of a module by navigating to your website's administrator panel followed by selecting the "Minecraft" tab. You will see an additional column reading "Server ID" for each server on your website.
Enabling Developer Mode
You can enable developer mode on your Enjin account in order to display useful information such as IDs throughout the Enjin platform in addition to gaining access to various advanced features. We strongly recommend that you enable this feature if you're going to be working with the Enjin API. You can enable developer mode by navigating to this link and checking the option "Enable Developer Mode".
Response Signature
You will need to follow the section "Enabling Developer Mode" in order to use this feature. Whilst performing requests via Javascript and forwarding that data externally, it may be useful to verify that the response hasn't been tampered with. You can achieve this via the response signature. In order to use this feature you must set the signature key which can be done via your website's API settings page. Once you have set a signature key, the request will return a "Signature" response header which can be compared with the HMAC SHA-256 of the API response and the key supplied in the API settings page.
Example: User Info
This simple example widget will display info about the user. HTML
<div id="api-widget-userinfo">
	<div class="avatar"></div>
	<p class="message"></p>
</div>
JavaScript
var url = "/api/v1/api.php";

var request = {
	"jsonrpc": "2.0",
	"id": Math.round(Math.random() * (999999 - 100000) + 100000),
	"method": "User.get",
	"params": {
	}
};

$(document).ready(function(){
	var widget = $('#api-widget-userinfo');

	$.post(url, JSON.stringify(request), function(response) {
		if (response.result) {
			if(response.result.logged_in == true) {
				var html = "Welcome " + response.result.link;
				html += "<br>Access: <b>" + response.result.registered + "</b>"
				widget.find(".message").html(html);
				widget.find(".avatar").html("<img src='" + response.result.avatar_medium + "'>");
			}
			else {
				widget.find(".message").html("Please <a href='login'>login</a> to the website!");
			}
		}
		else if (response.error)
			widget.text("Request Error: " + response.error.message);
	}, "json");
});
Example: Check if the user plays a game
This example widget will detect if the user is playing a certain game (in this case, Minecraft) and also display the total users on your website. HTML
<div id="api-widget-gameinfo">
	<p class="message"></p>
</div>
JavaScript
var url = "/api/v1/api.php";

$(document).ready(function(){
	var request = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Profile.getGames",
		"params": {
		}
	};

	var request2 = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Site.getStats",
		"params": {
		}
	};

	var widget = $('#api-widget-gameinfo');

	$.post(url, JSON.stringify(request), function(response) {
		if (response.result) {
			var found_game = false;
			for(var i in response.result.games) {
				if(response.result.games[i].game_id == 4923) {
					$.post(url, JSON.stringify(request2), function(response2) {
						if (response2.result) {
							widget.find(".message").html("Hey, it looks like you play <b>" + response.result.games[i].name + "</b>! Join our community of " + response2.result.total_users + " members who play too.");
						}
					});
					found_game = true;
					break;
				}
			}
			if(!found_game) {
				widget.find(".message").text("It looks like you don't play Minecraft - please add it to your Dashboard Games to participate in our community.");
			}
		}
		else if (response.error)
			widget.text("Please login");
	}, "json");
});
Example: Simple Shop
This example widget will display a simple list of shop categories and items, along with their prices. You can click on an item to purchase it. HTML
<div id="api-widget-shop">
	<div class='shop'>Loading shop ...</div>
	<div class='points' style='margin-top: 15px;'></div>
</div>
Javascript
var url = "/api/v1/api.php";

$(document).ready(function(){
	var request = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Shop.get",
		"params": {
			"preset_id": "28108588"
		}
	};

	var request_points = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Points.get",
		"params": {
		}
	};

	var widget_shop = $('#api-widget-shop .shop');
	var widget_points = $('#api-widget-shop .points');

	// Get the shop data
	$.post(url, JSON.stringify(request), function(response) {
		if (response.result) {
			var html = '';
			html += renderShop(response.result, '');
			widget_shop.html(html);
		}
		else if (response.error)
			widget_shop.text("Please login");
	}, "json");

	// Get the user's points
	$.post(url, JSON.stringify(request_points), function(response) {
		if (response.result) widget_points.html("You have <b>" + response.result + "</b> points to spend.");
		else widget_points.html("You do not have any points to spend.");
	}, "json");
});

function renderShop(data, html) {
	html += "<li><h3 class='category-name'>" + data.name + "</h3><ul>";
	if(data.categories !== undefined && data.categories.length) {
		for(var c in data.categories) {
			html = renderShop(data.categories[c], html);
		}
	}
	if(data.items !== undefined && data.items.length) {
		for(var i in data.items) {
			var price = '';
			if(data.items[i].price != undefined) price = "$" + data.items[i].price;

			var points = '';
			if(data.items[i].points != undefined) points = data.items[i].points + ' points';

			var ortext = '';
			if(price != '' && points != '') ortext = ' OR ';

			html += "<li class='item-name'><a href='/buy/" + data.items[i].id + "'>" + data.items[i].name + "</a> - " + price + ortext + points + "</li>";
		}
	}
	html += "</ul></li>";
	return html;
}