Skip to main content

Specification

1. Overview​

To make CLI HTTP requests to the PGOS CLI Server, you need to put essential parameters in the HTTP Header, request payload in the HTTP Body, and send it to the correct host. In this document, we'll cover the basics of each component and how to put them together to make a correct HTTP request.

2. Components​

2.1 CLI HTTP Request​

CLI HTTP API's request is specific to your title region, it consists of the following parts:

  • Domain: Domain name, specific to your title region, Obtain the domain name on the web portal here, please use CLI API Domain.
  • Service Path: Service path, if you are accessing title CLI commands, fill in /index/client/api, if you are accessing title region CLI commands, fill in /console/client/api.
  • Protocol: Protocol, fixed to https.
  • HTTP Method: HTTP method, fixed to POST.
  • HTTP Header: HTTP header, contains the necessary parameters, which will be introduced in detail later.
  • HTTP Body: HTTP body, contains the JSON data of the request, which will be introduced in detail later.
  • HTTP Response: HTTP response, contains the JSON data of the response, which will be introduced in detail later.

image-20250226155237842

2.2 Server Key​

image-20231211141859964

Server keys are configured on the title settings page of the web portal, only using Server keys can access the CLI HTTP API.

serverkey

  • The secret_id is the first part of the server key: LTRN.
  • The secret_key is the last part: NANI-D3TK-YQBM-MOUX.

Please note that the composition of the secret key: Secret ID and Secret Key. In the following steps, the Secret ID part will be put directly in the HTTP header, and the Secret Key part will be used to calculate the Server Ticket.

2.3 Title ID & Title Region ID​

In PGOS, "Title" stands for the game. Each title is isolated and does not affect each other. Normally there are multiple "Regions" for each title. That's the meaning of Title ID and Title Region ID. Put them in the HTTP header to identify the specific region of your game.

tip

📌 If you access the Title CLI Commands, you can omit the Title Region ID field.

2.4 Server Ticket​

Server Ticket is essentially a piece of JSON data encrypted by the AES CBC algorithm.

Let's use the following example to demonstrate the process::

  • Title ID: 5
  • Title Region ID: cngz_5_478_test
  • Server Key: LTRN-NANI-D3TK-YQBM-MOUX

First, you need to generate the plain text of JSON data.

tip

The ticket algorithm below is consistent with the ticket calculation method in the Backend HTTP API. For details, please refer to Backend HTTP API.

The following fields are introduced:

  • Title ID: the title ID of your game.
  • Title Region ID: the title region ID of your game.
  • Secret ID: the first part of the server key.
  • Time: the current timestamp in seconds, which is the number of seconds since 1970-01-01 00:00:00 UTC.
{ "title_id": "5", "title_region_id": "cngz_5_478_test", "secret_id": "LTRN", "time": 1600531200 }

Then make the AES Key, which is the secret_key but wipe all the - delimiters.

NANID3TKYQBMMOUX

Finally, invoke the AES CBC algorithm to encrypt the JSON data above.

Two parameters are required to run the AES CBC algorithm: AES Key and IV. The IV is a constant value for all PGOS requests: $3,.'/&^rgnjkl!#.

AESKey: NANID3TKYQBMMOUX
IV: $3,.'/&^rgnjkl!#

The Base64 string of the final product of AES CBC algorithm is the ServerTicket.

tip

The generated Server Ticket is valid for 2 hours and needs to be regenerated after expiration.

2.5 Command & Params​

The payload of the request is placed in the request body, which is a JSON object containing two fields:

  • Command: Command name, different commands implement different features.
  • Params: Command parameters, specific command parameters.

The Command and Params above can be found here.

tip

In the current version, among all the commands listed in the Title Command Reference and Title Region Command Reference, the following commands are not supported:

  • create-title-file: Require file upload, the current command is not supported temporarily.
  • create-build: Require file upload, the current command is not supported temporarily;
  • create-virtual-server: Require file upload, the current command is not supported temporarily.

If you need to use these commands, please use the CLI tool.

{
    "Command": "<Command>",
    "Params": {
        "<Key>": "<Value>"
    }
}

2.6 Put it all Together​

To sum up, we need a POST request to the URL specific to your title region, then set the required HTTP headers, and finally put the request JSON data in the HTTP body.

If you access the Title CLI Commands, you can omit the Title Region ID field.

POST https://pgos.intlgame.cn/index/client/api HTTP/1.1
Host: pgos.intlgame.cn
Content-Type: application/json
SecretID: LTRN
ServerTicket: <Server Ticket Here>
TitleID: 5
TitleRegionID: 

{
    "Command": "<Command>",
    "Params": {
        "<Key>": "<Value>"
    }
}

2.7 Response Result​

The response result is a JSON object, which contains three fields:

  • errno: Error code, 0 means success, non-zero means failure.
  • errmsg: Error message, empty string means success, non-empty string means failure.
  • data: Response data, the structure of which is different for different commands.
{
    "errno": 0,
    "errmsg": "",
    "data": {}
}

3. Debug HTTP API via Postman​

While you can access the HTTP API by writing code, you may need to debug the HTTP API first to ensure you understand the related protocols and parameters before starting to write the code.

You can follow these steps to use Postman to access the HTTP API.

image-20231207163354225

Four components are needed to invoke HTTP API via Postman.

  • Determine the HTTP Method and URL, where the URL includes the service path to be accessed.
  • Fill in the HTTP Header, using the variable {{ServerTicket}} for the ServerTicket field.
  • Fill in the HTTP Body, adhering to the JSON format specified in the interface protocol.
  • Fill in the Pre-request Script by copying the following code and change the required fields for your project.

4. Access CLI HTTP API via Code​

The following samples demonstrate how to access HTTP API in different languages.

  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://cngz.pgos.intlgame.cn/console/client/api"
    method := "POST"

    payload := strings.NewReader(`{
        "Command": "<CLI Command>",
        "Params": {
            "<Key>": "<Value>"
        }
    }`)

    client := &http.Client {}
    req, err := http.NewRequest(method, url, payload)
    if err != nil {
      fmt.Println(err)
      return
    }

    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("SecretID", "<SecretID>")
    req.Header.Add("ServerTicket", "<ServerTicket>")
    req.Header.Add("TitleID", "<TitleID>")
    req.Header.Add("TitleRegionID", "<TitleRegionID>")

    res, err := client.Do(req)
    if err != nil {
      fmt.Println(err)
      return
    }
    defer res.Body.Close()

    body, err := ioutil.ReadAll(res.Body)
    if err != nil {
      fmt.Println(err)
      return
    }
    fmt.Println(string(body))
  }