Sign in

Authentication

The SCILL API uses API Keys to authenticate requests. API keys can be generated in the SCILL Admin Panel and are linked to a specific product that you also create in the Admin Panel.

The API-Keys carry many privileges and are directly linked to your account, so make sure that you keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is implemented via bearer auth by using this header:
Authorization: Bearer [API-KEY/Access-Token]

Base URL

https://us.scillgame.com

Your API-Key

A sample key is included in all examples to get you started quickly.

To test requests with your own product account, replace the API-Key with your own key you received after creating a product in the SCILL Admin Panel.

User Ids

Within this document we often refer to “User Ids”. As this platform does not know anything (personal) about your users we need to make sure that events you send for a user to drive our services can be linked to the same user using your application.

We also need to make sure that nobody can hack the system to query data for other users. If you have users, you will have a secure system to authorize them, and you will have some sort of a unique id to identify them. You can either send this user id alongside events and when creating the access token (see below) or you can even create a special user id for SCILL that you store with your user data to make things even more secure.

SCILL just stores those User Ids in

Access Tokens

Some endpoints require an access token. This is required if your client (i.e. JavaScript in a website or a game client) directly communicates with the SCILL backend. In these unsecure areas, hackers could extract your API-Key and use it to hack or manipulate their state within your application (faking challenge progress for example). To prevent this, your client asks your backend to generate an access token which then uses an API based SCILL backend to create and sign the access token. In subsequent calls to client APIs you just send the access token instead of the API key to securely identify the user and your game.

The process looks like this:

Getting an access token

Getting an access token

This is the flow - you only have to do that once per user session and store the access token somewhere to reuse it whenever your client calls a request that requires an access token.

  1. Your app calls your own backend and sends a session token
  2. Your backend extracts a user id from the session (at one’s own discretion) and requests SCILL backend with API-Key and user id to generate an access token
  3. SCILL backend encodes an access token (encoding app and user) and returns it
  4. Your backend returns that access token as a response to the initial client request
  5. Your client stores the access token somewhere and uses it in the header (Authorization: Bearer [Access-Token]) or as a parameter to SCILL SDK calls.
Generate Access Token

Use this endpoint to generate the access token:

URL v1/auth/access-token
Method POST
Authentication API Key
Payload
{
  "user_id": "[USERID]"
}
Parameters

USERID string REQUIRED

This is the user id you also use for sending events and that you can use to identify your user later. Instead of sending the “real” user ids, you can also generate a special user id (or encrypt it) for SCILL. However as we’ll send you back this user id in Webhooks you must be able to find the corresponding user if you receive this id.

Generate Auth Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR59...."
}
Lifetime of Access Tokens

Access token expire after 24 hours. You may not store access tokens to any form of persistent storage. You must also make sure, that you check responses of REST-API calls for their HTTP Status Code. If status code returned is 403 the access token is not valid anymore, and you need to generate a new one before trying calling the same REST-API function again.

As you also have a rate limit alongside the event limit we’d suggest that you don’t generate a new access token with every REST-API call but rather caching them. However, in this case you need to make sure the token does not expire.

To prevent that, best place to generate/update access tokens is in either of these events:

  • App is started
  • App is activated from background
  • App/Game came back from stand-by, hibernate.

To prevent any issues for games/apps that tend to run without interruption for more than 24 hours, you can also just create an interval of 8 hours to generate new access tokens.

Please note

Please note: This is the general documentation of whats going on behind the scenes and depending on your use case you will need to implement that.

For most common use cases, like Steam Games we already have prepared that backend for you and you will not have to implement that yourself.

More info on that can be found in the Quick Start Guides.

POST scill/generate-access-token
// This is a function you have to implement that calls your backend which calls SCILL API to generate
// an access token with the user id. This is your user id and can be a Steam-ID, or your own user identification.
const getAccessToken = async function() {
  // Your client will have some sort of token or session, this is up to you how to secure this
  const session = getSessionId();
  return fetch("https://www.example.com/scill/generate-access-token", {
    method: "POST", 
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({session: session})
  });
}

const accessToken = await getAccessToken(); const userChallengeId = await scill.buyChallenge('example-product', 'example-challenge', accessToken);

POST v1/api/auth/access-token
// This example implements a NodeJS backend receiving sessions from your client and asking SCILL
// to generate an access token for the userId "encoded" in/via the session.

const express = require('express');
const bodyParser = require('body-parser');
const SCILL = require('@scillgame/scill-js');

const app = express(); const port = 80;

app.use(bodyParser.json()); app.use(bodyParser.urlencoded({ extended: false }));

app.get('/scill/generate-access-token', (req, res) => { // This is th session sent by the client (see example above) const session = req.body.session;

// You will be able to extract or query the user id based on the session const userId = getUserIdFromSession();

// Call SCILL backend to generate an access token encoding user and API-Key return scill.generateAccessToken(userId).then(accessToken => { // return access token return res.send(accessToken); });
});

app.listen(port, () => { console.log('Example app listening at http://localhost:${port}'); });

Realtime Challenges

Use this endpoint to generate a topic for our MQTT server. Subscribe to that topic to get realtime updates whenever a challenge changes in the backend for this user.

URL v1/api/v1/auth/user-challenges-topic-link
Method GET
Authentication Access Token

More info on how to use the topic in our Realtime Updates section of the API reference documentation.

GET v1/api/v1/auth/user-challenges-topic-link
const scill = require('@scillgame/scill-js')
const accessToken = getAccessToken();
const authApi = scill.getAuthApi(accessToken);
authApi.getUserChallengesNotificationTopic().then(notificationTopic => {
  // Get the notification topic and subscribe via MQTT on this to receive updates  
});
The Response
{
  "topic":"21666d85fe0e746f96bb9a..."
}

Realtime Battle Passes

Use this endpoint to generate a topic for our MQTT server. Subscribe to that topic to get realtime updates whenever a challenge in a battle pass changes in the backend for this user.

URL v1/api/v1/auth/user-battle-pass-topic-link?battle_pass_id=BATTLE_PASS_ID
Method GET
Authentication Access Token
Parameters

BATTLE_PASS_ID string REQUIRED

This is the battle_pass_id of the BattlePass. Use this to set the id of the battle pass to get updates for.

More info on how to use the topic in our Realtime Updates section of the API reference documentation.

GET v1/api/v1/auth/user-battle-pass-topic-link
const scill = require('@scillgame/scill-js')
const accessToken = getAccessToken();
const authApi = scill.getAuthApi(accessToken);
authApi.getUserBattlePassNotificationTopic(battlePassId).then(notificationTopic => {
  // Get the notification topic and subscribe via MQTT on this to receive updates  
});
The Response
{
  "topic":"21666d85fe0e746f96bb9a..."
}