🗝️ AuthKit

A kit that helps you with authenticating and identifying users.

What is AuthKit?

Before talking about Authkit, it is important to understand that users playing your game on Trail aren't always registered users. As we mentioned in the What is Trail? article; Trail is an ultra-accessible platform which means that a player can access any game on the Trail platform at any point in time. Your game can be played by users that aren't logged in or even signed up to the Trail platform. This is where AuthKit comes in; it helps you verify and authenticate users on the Trail platform when required. It does so by hooking up to your backend and provide access to Trail's backend to verify any user logged in on the platform.


Singleplayer vs multiplayer games

AuthKit can work with singleplayer games. You are able to request both a Play Token ID and a Game User ID directly from the SDK. However, you'll get the most out of AuthKit if you couple it with your own backend.

User's ID journey

Before we look at a user's ID journey on Trail, 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 Trail player and to obtain their Game User ID.

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

User's ID journey.User's ID journey.

User's ID journey.

It starts with a request submitted from your game client to the Trail 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 (Trail 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

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 SDK.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

Getting the Game User ID using the Play Token

Before we get the Game User ID, it is recommended that you verify the Play Token with the Trail 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 nature of 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.

Updated 4 months ago

🗝️ AuthKit

A kit that helps you with authenticating and identifying users.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.