Authentication

API users must have a registered Gengo account to acquire a pair of keys - a public key and private key. The api_key is used to identify a user, and the private_key is used to authenticate each API call. The combination effectively functions as a user name and password. Therefore you should keep the private_key private.

The keys are created and retrieved from the account settings page.

Every restricted (non public) REST call will need to be authenticated by Gengo as below.

Signing Calls

All authenticated calls must be signed:

  1. Get the current Unix epoch time as an integer
  2. Insert the time as the value to a ‘ts’ key in your argument list
  3. Calculate the SHA1 hash of the timestamp against your private key
  4. Append the value of this hash to the argument list as a parameter named api_sig

Example API authenticated call

 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
#!/usr/bin/python
# -*- coding: utf-8 -*-

from hashlib import sha1
import hmac
import json
import requests
import time

if __name__ == '__main__':
    PUBLIC_KEY = 'your public key'
    PRIVATE_KEY = 'your private key'

    # submit a comment for job ID 20
    JOB_ID = '20'
    COMMENT = 'Please use British spelling'
    URL = "http://api.gengo.com/v2/translate/job/{0}/comment".format(JOB_ID)
    header = {"Accept": "application/json"}

    data = {
        # 'data' must be flattened. We use json.dumps()
        "data": json.dumps({"body": COMMENT}, separators=(',', ':')),
        "api_key": PUBLIC_KEY,
        "ts": str(int(time.time()))
    }

    # use your private_key to create an hmac
    data["api_sig"] = hmac.new(
        PRIVATE_KEY,
        data["ts"],
        sha1
    ).hexdigest()

    post_comment = requests.post(URL, data=data, headers=header)
    res_json = json.loads(post_comment.text)

    if not res_json["opstat"] != "ok":
        msg = "API error occured.\nerror msg: {0}".format(
            res_json["err"]
        )
        raise AssertionError(msg)
    else:
        print(res_json)