Authkit

AuthKit is Pley's tool to identify, verify, and authenticate users on the Pley platform who is trying to play your games. It integrates with your back-end and provides access to Pley's backend to verify any logged-in users on the platform.

📘

Authentication is Unique!

How authentication is solved is often unique, with each game having its own technology to solve it. Authkit is lightweight — it can be adapted to integrate Pley with the exact authentication of your game.
If you need help with this, we'd love to help you through our developer discord.

User's ID Journey

Before we look at a user's ID journey on Pley, it is better to define two pieces of information first:

• Game User ID: This is a unique, permanent ID that identifies the user currently playing your game. The Game User ID is primarily used to authenticate a user when dealing with sensitive processes (for example when buying an item).
• Play Token: This is a unique token generated every time a user starts a new session for your game (similar to a session ID). This token is only valid for a limited time (~30 minutes). The Play Token is primarily used to verify that a player is a Pley player and to obtain their Game User ID.

With that out of the way, let's look at the user's ID journey:

It starts with a request submitted from your game client to the Pley SDK using AuthKit. The SDK provides a Play Token to your game client. Your client would then send it to your backend which in turn would send it over to our server (Pley JSON API) that verifies it. If it checks out, it sends back the Game User ID to your backend. At that point, you can store the Game User ID on your backend for further use and send an "authentication completed" flag to the client.

Getting and Sending Play Token

📘

API References

You can find the methods called in the references for Unity SDK AuthKit and for the C SDK AuthKit.

Getting and sending Play Token from the SDK is simple.

// Remember to initialize the SDK first. 

// Request a Play Token ID from the SDK:
private string GetTrailPlayToken()
{
    return Trail.AuthKit.GetPlayToken();
}

// Now that we have the Play Token ID, we send it over to your backend so the backend can send a request to Trail's server.
private void SendTokenToBackend()
{
    // Your backend's server send request
  MyBackend.AuthenticateUsingTrail(GetTrailPlayToken());
}

Getting the Game User ID using the Play Token

📘

HTTP API References

You can find the references for the Pley HTTP API by clicking here.

Before we get the Game User ID, it is recommended that you verify the Play Token with the Pley server first. To do that, simply create a HTTP request using cURL, from your backend:

curl -X POST \
  https://json.api.beta.trail.gg/v2/auth-kit/verify-play-token \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "play_token": "users-play-token"
  }'

Your backend will receive a JSON response back that looks like this:

{
  "data": {
    "game_user": {
      "game_user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "username": "Tornado92"
    },
    "game_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

A few things to note; while this JSON contains the Game User ID, it also contains the username as well. Another thing is that you can check the status code for this response. As customary we use 200 for a valid response (i.e. verified Play Token) and a 400 as a bad request (i.e. corrupt Play Token)

📘

We've included the Game ID within the response JSON so you can identify a specific game. This can be useful if you have multiple games hooked to the same backend service and need verification. This is also used by us to authenticate you as a developer when a request is sent.

Verification Frequency

How often you need to verify a user depends on the communication between your game and the backend. If your communication with the backend is stateless (i.e. communicating with an HTTP API without sessions) we recommend you either verify with each call or at least with very sensitive calls (i.e. calls that will modify your database).
If your communication with the backend is stateful (for example using WebSocket) then you can verify once at the beginning of said communications.

🚧

Play Token ID Expires

As mentioned above, Play Tokens expire after a while automatically (every 30 minutes or so). We recommend you request the Play Token when you're doing any verifications just in case.

❗️

SDK Game User ID

The Game User ID is available from within the SDK. However, the method call isn't meant to be used for verification as the resulting Game User ID can be easily tampered with. The purpose of this method call is to help in error reporting for example.