Warning: This version (v1) of the API will be deprecated on May 1st 2015


One of the not-so-great things about developing games using JavaScript, is your client-side code can be read and executed by anyone. That makes something like leaderboards somewhat easy to send altered data to.

To counter this, we allow you to optionally encrypt any data sent to Clay.io's server. We do this using JWT.

Do make sure you have the encryption setting turned on in the Settings page of your game's Developer Area, otherwise none of this will work. You are able to specify the methods you want to be encrypted as well. By default this is just:

  1. Clay.Player.fetchItems()
  2. Clay.Leaderboard.post()
  3. Clay.Achievement.award()

When you have encryption turned on for certain methods, everything you must pass to Clay.io (that would would normally do in the options object), must be passed as { jwt: "Your JWT encoded string" }. To get the JWT encoded string, you must use a library for JWT encryption and the secret key for your game. You can find the secret key for your game on the settings page in the Developers' Area.

Simply passing, for example, { score: 99999 } will not work when you have encryption turned on for Leaderboard.Post. You will have to pass { jwt: "WHATEVER_IS_GENERATED" }.

The object you will need to encrypt is simply the standard options object with two additional properties. The first: identifier can be grabbed with Clay.Player.identifier. The second: timestamp is simply the current UNIX timestamp. This is so a player, for example, can't post their own leaderboard score twice.

We have two backend libraries written, one for node.js and one for PHP. They are both fairly simple and just set and store the user identifier and timestamp as properties, so every time you call our encryption method, you don't have to worry about passing the identifier or timestamp again and again.

An example scenario of implementation (using one of our libraries) would be:

  1. Client: Grab Clay.Player.identifier, send to backend
  2. Backend: Call the storeIdentifier( identifier ) method of our class
  3. Backend: To grant achievement, call our encode( obj ) method on an object (or array for PHP) of { id: 3 } where 3 is just our example achievement ID
  4. Backend: Send the JWT that is generated to the client
  5. Client: ( new Clay.Achievement( { jwt: "JWT_THAT_WAS_GENERATED" } ) ).award();

Provide Feedback

We take customer support, and the quality of our developer tools and documentation very seriously. We want to hear how you think we can improve our documentation! Let us know if anything is missing, or unclear on this documentation page, and we'll get that fixed!