Using the HTTP API

Introduction

The Trail HTTP API is still mostly a collection of endpoints that are necessary to enable features that require communication between your game's backend and Trail.

Specifically, it allows you to:

• Verify a user's play token to ensure the user is real.
• Retrieve and consume entitlements, related to in-game purchases.
• Send notifications.

But we are also adding more endpoints on a case-by-case basis based on the needs of individual developers, so if you are missing any functionality please reach out to us and we will help you out 👍

Base URL

All requests use the same base URL: https://json.api.beta.trail.gg/v2

Authentication

Requests need to be authenticated using an API token. You can find your API token in the Game Manager by navigating to Your Game > Game settings.

You authenticate your requests by passing the API token as a Bearer token in the authorization header of the request, like so: Authorization: Bearer your-api-token

Message format

The API only accepts data sent as JSON and all data returned will also be sent as JSON. So make sure that your content-type header is set to JSON, i.e.

Content-Type: application/json

Example of a JSON-object in a request:

{
  "key_1": "value_1",
  "key_2": "value_2",
  ...
}

Requests

Data sent in requests should be sent as a plain JSON-object.

Responses

A successful request will receive a response with a status code 200 which contains a data object or list depending on the request.

Example of a response from a successful request:

{
  "data": {
    "key_1": "value_1",
    "key_2": "value_2",
    ...
  }
}

Or:

{
  "data": [{
    "key_1": "value_1",
    "key_2": "value_2",
    ...
  }, {
    "key_1": "value_1",
    "key_2": "value_2",
    ...
  }]
}

Errors

If a request fails you will receive a response with a status code describing the issue. We use the following status codes for errors:

400 - Bad request - Something is wrong with your request.

403 - Forbidden - You do not have the appropriate permissions for this request.

404 - Not found - The endpoint does not exist.

500 - Internal server error - The backend is experiencing issues. Please try again later, if the issue persists contact support.

If the response has the status code set to 400, the response body will contain an error object describing why the request failed.

Example of a response for a failed request with status code 400:

{
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "message": "invalid notification_type"
  }
}

Example Request

Here is an example request of what it could look like when sending a push notification to your users.

Example Request:

curl -X POST \
  https://json.api.beta.trail.gg/v2/notifications-kit/broadcast \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "game_id": "your-game-id",
    "type": "match_available",
    "target": {
        "region": "eu"
    }
}'

Example Response:

{
  data: {
    "users_targeted": 42
  }
}

AuthKit

verify-play-token

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"
  }'

Response:

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

Validates that the play token is valid, and gives back the game user associated with the play token.

HTTP Request

POST /auth-kit/verify-play-token

Parameters

Name	Type	Description
play_token	string	game user's play token

Returns

Name	Type	Description
game_user	Game user
game_id	string

Game user

Properties

Name	Type	Description
game_user_id	string
username	string

get-game-user-id

POST /auth-kit/get-game-user-id

Parameters

Name	Type	Description
game_id	string	game id
email	string	user's email

Returns

Name	Type	Description
game_user_id	string

Finds a user by their email and returns their game_user_id in the game identified by game_id.

NotificationsKit

broadcast

curl -X POST \
  https://json.api.beta.trail.gg/v2/notifications-kit/broadcast \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "game_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "weekend_sale",
    "target": {
      "region": "eu",
      "has_purchased: "true",
    }
  }'

Response:

{
  "data": {
    "users_targeted": 42
  }
}

Sends a notification to all users that match the criteria specified by target.

HTTP request

POST /notifications-kit/broadcast

Parameters

Name	Type	Description
game_id	string	ID for the game that is sending the notification
type	string	notification type, e.g. weekend_sale
target	object	e.g. { "region": "eu", "has_purchased": "true" }

Returns

Name	Type	Description
users_targeted	int32	amount of users targeted by the notification

PaymentsKit

get-entitlements

curl -X POST \
  https://json.api.beta.trail.gg/v2/payments-kit/get-entitlements \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "game_user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }'

Response:

{
  "data": [{
    "entitlement_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }, {
    "entitlement_id": "xxxxxxxx-xxxx-xxxx-xxxx-yyyyyyyyyyyy",
    "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }]
}

Retrieves a list of entitlements for a user.

HTTP request

POST /payments-kit/get-entitlements

Parameters

Name	Type	Description
game_user_id	string	ID of the user you want to retrive entitlements for
include_sandbox	boolean	If true sandboxed entitlements will also be returned, if false they will not. Omitting this parameter is the same as setting it to true.
include_consumed	boolean	If true consumed entitlement will also be returned, if false they will not. Omitting this parameter is the same as setting it to false.

Returns a list of entitlements

Name	Type	Description
entitlement_id	string
product_id	string	ID for the product associated with the entitlement
in_sandbox	boolean	Indicates whether the entitlement was created in sandbox mode
consumed_at	string	The date the entitlement was consumed. It is returned as a string with the date in ISO 8601 format, .e.g 2012-04-23T18:25:43.511Z. If the entitlement has not been consumed, this field will be omitted.

Properties

Name	Type	Description
game_user_id	string
username	string

consume-entitlement

curl -X POST \
  https://json.api.beta.trail.gg/v2/payments-kit/consume-entitlement \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "entitlement_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }'

Response:

{
  "data": {}
}

Consumes an entitlement.

HTTP request

POST /payments-kit/consume-entitlement

Parameters

Name	Type	Description
entitlement_id	string	ID for the entitlement to be consumed

Returns

Name	Type	Description
N/A

get-order

HTTP request

POST /payments-kit/get-order

Parameters

Name	Type	Description
game_id	string	ID of the game
invoice_number	string	Invoice number
in_sandbox	boolean	Whether it's a sandboxed order or not

Returns

Name	Type	Description
game_user_id	string
order_id	string
datetime	string	Date and time when the order was created in ISO 8601 format, .e.g 2012-04-23T18:25:43.511Z.
in_sandbox	boolean
email	string	Email given by the user when the order was placed.
full_name	string	Full name given by the user when the order was placed.
tax_country	string	ISO 3166-1 alpha-2 code of the country where the order is taxed.
amount	number	The amount of the order.
currency	string	The currency of the order, this applies to the line_items property.
line_items	LineItem[]	List of LineItems

LineItem

Name	Type	Description
product_id	string
product_name	string
price_tier	number
price_tier_name	string
price_amount	number
entitlement_id	string