Sign-hash generation

To make API requests to the base zeuz API, you must first log in to zeuz. You also need to authenticate every API request you make after login by attaching a sign-hash to the request; the sign-hash is your API request’s authentication credentials.

You generate the sign-hash using data zeuz returns to your login function.

You must set up both the login and sign-hash generation in scripts. You can generate the sign-hash in the same script as the login, or in the same script as your API request, depending on how you choose to set it up.

The steps and example code snippets below show you what must be in your sign-hash generation script. They cover task 4. Generate a sign-hash to attach to your API requests, listed in API authentication overview.

See Example code for a full working example that covers the following two tasks listed in API authentication overview: 3. Log in to zeuz and generate a session key and 4. Generate a sign-hash to attach to your API requests.

Warning: You may not need a sign-hash generation script.

See Do I need a sign-hash generation script? below.

Info: Do I need a sign-hash generation script?

Before you start, see the API introduction to check whether you can access the zeuz API using one of the wrappers provided in the SDK download or the SDK in Go. If you can use a wrapper or the SDK in Go you don’t need to write your own authentication scripts.

You must access the zeuz base API directly if:

  • You develop your game in a language other than Unity, Unreal, or Go, or

  • You want to use the zeuz API to build tools around your game, for example to integrate your game into your CI/CD pipeline.


Sign-hash generation flow

The following image summarises the sign-hash generation flow, using the function names and variable names from the example code.

Image: sign-hash generation flow.

Image: sign-hash generation flow.

Before you begin

Before you begin to generate a sign-hash, ensure that you have:

  • Read the introductory information about the zeuz API.

    See API introduction.

  • Read the summary of the zeuz base API authentication process, so you know what you need to set up.

    See API authentication overview.

  • Created a script to log in to zeuz and generate a session key.

    See API login for details.

How to generate a sign-hash

You use the session key from your login script, together with a new nonce and a new timestamp, to generate another hashed password called the sign-hash.

You then attach the sign-hash to your API requests until the session key expires (24 hours from the time the session key is created).

The following example C++ code:

  • Generates a sign-hash
  • Sends a JSON packet to the auth_check API endpoint, and
  • Parses the return value for an invalid_session or session_expired error.

If the login session is valid, you can continue and send further API requests. If it’s invalid you need to perform a new login.

Example snippet in C++:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
#include <jsoncpp/json/writer.h>
#include <jsoncpp/json/reader.h>
  
// Check if the session timestamp is still valid
bool ZeuzApi::check_session(long now, LoginData login_data) {
    // Check that the expiry time is at least 60 seconds away
    if (now > (login_data.ValidThru - (60 * 1000000))) {
        return false;
    }
    return true;
}

// Format according to auth_check API endpoint
// See: API Reference doc.zeuz.io/reference#auth_check
std::string format_to_json_payload(std::string request_id, std::string session, std::string sign_hash, long time, std::string session_id) {
   Json::Value data;
   Json::FastWriter writer;
   data["ReqID"] = request_id;
   data["Session"] = session;
   data["SignHash"] = sign_hash;
   data["Time"] = Json::Int64(time);
   data["Data"] = session_id;
   return writer.write(data);
}

// Call the auth_check API endpoint to verify whether
// the logged-in session is still valid
bool ZeuzApi::auth_check(LoginData login_data) {
   auto now = zeuz_now();
   if (!check_session(now, login_data)) {
       // If the session has expired, it is no longer valid
       return false;
   }
   auto request_id = generate_nonce(10);

	// Generate a sign-hash
auto sign_hash = zeuz_hash(std::to_string(now) + request_id + login_data.SessionKey);

	// Attach the sign-hash and other required data to the request
auto data = format_to_json_payload(request_id, login_data.SessionId, sign_hash, now, login_data.SessionId);
   response = post_request("https://zcp.zeuz.io/api/v1/auth_check", data);

   // Parse the JSON response and extract the values
   Json::Reader reader;
   Json::Value response_json;
   if (!reader.parse(response, response_json)) {
      // Note: In production code, use a C++ exception instead
      throw std::string("could not parse response data ( " + response + ")");
   }
 
   // Check whether the error field is set
   auto error = response_json["Error"].asString();
   if (!error.empty()) {
      if (error.rfind("invalid_session", 0) == 0 ||
          error.rfind("session_expired", 0) == 0) {
          // If the session has expired, you need to perform another login
          return false;
      } else {
          throw std::string("could not check session (" + response + ")");
      }
   }

   // If no error is received, the session is valid
   return true;
}

Next: Attach the sign-hash to your API requests

Now that you’ve generated a sign-hash, you can attach it to your API requests. See Example 4 in Example code for an illustration of this.

See Design considerations for some approaches you can take to work around the session key expiry limitation.


2021-aug-09 Page updated with editorial review: added sign-hash generation flow image.

2021-may-12 Page added with editorial review.


Last edited on: October 13, 2021 (149a70bd)