The GPI Translation Services API – Part 2

May 12, 2016

The Globalization Partners International (GPI) Translation API is a technology agnostic platform which enables companies to access GPI's translation services provided by our global team of professional, native-speaking translators.


Part one of the GPI Translation Services API series, I briefly explained how it works. In part two of this series, I will give an in-depth guide to using the API.

Getting Started with the GPI Translation API


The GPI Translation API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication.


The following describes the high-level process for authentication:


  1. Developer concatenates selected elements of the request to form a string.
  2. Using your GPI-SECRET-KEY, the developer calculates the HMAC of that string.
  3. Developer includes the computed HMAC signature as a parameter of the request by using the Request Signing syntax described below.
  4. GPI receives your request, we fetch the GPI-API-KEY that you claim to have and use it in the same way to compute a signature for the message it received.
  5. If the signature we compute matches the signature in your request, we conclude that the requester has access to the GPI-SECRET-KEY and the request is authenticated.
  6. If the two signatures do not match, the request is dropped and the system responds with an error message.

How it Works


The GPI Translation API uses both the standard HTTP Authorization header and a custom header to pass authentication information.


The headers have the following form:


Authorization: GPI-HMAC Signature
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8

Developers are issued a GPI-API-KEY and GPI-SECRET-KEY when they register. For request authentication, the GPI-API-KEY identifies the developer making the request.


The Signature is the HMAC-SHA256 encoded representation of selected elements from the request, and will vary from request to request.


If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the GPI-SECRET-KEY.


The request will then be processed under the context of the developer to whom the key was issued.

Request Signing


The following illustrates the construction of the Authorization request header:


Authorization = "GPI-HMAC" + " " + Signature;
Signature = Base64( HMAC-SHA256( Your-GPI-SECRET-KEY, UTF-8-Encoding-Of( StringToSign ) ) );
StringToSign = HTTP-Verb + "\n" +
    Content-MD5 + "\n" +
    Content-Type + "\n" +
    Date + "\n" +
    CanonicalizedHeaders +
CanonicalizedResource = [ "/" + <resource-endpoint-absolute-path> ];
CanonicalizedGpiHeaders = <described below>

NOTE: In the example above, "\n" means the Unicode code point U+000A, (i.e. called newline character).


HMAC-SHA256 is a hashing algorithm that takes two byte-strings, a key and a message as input


For the GPI Translation API request authentication, use your GPI-SECRET-KEY as the key, and the UTF-8 encoding of the StringToSign as the message.


The output of HMAC-SHA256 is also a byte string, called the digest.


Finally, the Signature request parameter is constructed by Base64 encoding this digest.

Canonicalized GPI Headers


To construct the CanonicalizedGpiHeaders part of StringToSign, select all HTTP request headers that start with 'X-GPI-' (using a case-insensitive comparison), and use the following process:


  1. Lowercase each HTTP header name. For example, 'X-GPI-KEY' becomes 'x-gpi-key'.
  2. Sort the collection of headers in lexicographical order by header name.
  3. Merge liked-named header fields into a single entry '<header-name>:<comma-separated-value-list>', without any whitespace between values.
  4. Convert multi-line headers into a single line by replacing the whitespaces (including new-line) with a single space.
  5. Trim any whitespace around the colon in the header. For example, the header 'x-gpi-key: 12345' would become'x-gpi-key:12345'.
  6. Append a newline character (U+000A) to each canonicalized header, concatenating all headers into a single string.

Positional vs. Named HTTP Headers


The first few header elements of StringToSign (Content-TypeDate, and Content-MD5) are positional. The header names are not included in StringToSign but only their values from the request.


In contrast, the 'x-gpi-' elements are named. Both the header names and the header values must appear in StringToSign.


If a positional header required by StringToSign is not present in your request, use an empty string ("") for that position.

Specifying the Date Header


All authenticated requests must include the Coordinated Universal Time (UTC) timestamp for the request. You can specify the timestamp either in the x-gpi-date header, or in the standard HTTP/HTTPS Date header.


If both headers are specified on the request, the value of x-gpi-date is used as the request's time of creation.


NOTE: Some HTTP client libraries do not expose the ability to set the Date header for a request.


In cases like these, you can set the timestamp for the request by using an x-gpi-date header instead. Therefore, if you include the x-gpi-date header, use the empty string for the Date when constructing the StringToSign.



For the following examples, we will use the (non-working) keys in the following table.


Key                                        Value

GPI-API-KEY                            C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8

GPI-SECRET-KEY                     s!kNYGY,PO4rUvj=o%:h3p/VpaP+!coQ+pJfPsbg2]m.=akLjC%=uqurW%f&~<gE

Example 1


Request - GET Quote #2510


 GET /quotes/2510 HTTP/1.1                                                      
Date: Tue, 29 Jul 2014 10:00:00 +0000
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8



Tue, 29 Jul 2014 10:00:00 +0000\n

Example 2


Request - DELETE Quote #2510


 DELETE /quotes/2510 HTTP/1.1                                                      
Date: Tue, 29 Jul 2014 10:00:00 +0000
Authorization: GPI-HMAC NGI0ZjJiNDZjMWJiMDQxM2M0ZmY5ZmEyNzgxMjk4MGU3YjgxNmJlN2Q0YzMzMjljMTkzNjdiN2NiY2Y5NWNmOA==
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8


Tue, 29 Jul 2014 10:00:00 +0000\n

Example 3


Request - GET Quote #2510 using X-GPI-DATE


 GET /quotes/2510 HTTP/1.1                                                       
Date: Tue, 29 Jul 2014 10:00:00 +0000
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8
X-GPI-Date: Tue, 29 Jul 2014 10:00:00 +0000


x-gpi-date:Tue, 29 Jul 2014 10:00:00 +0000\n


Notice how the 'X-GPI-' headers are sorted, trimmed of whitespace, and converted to lowercase.


NOTE: Multiple headers with the same name have been joined using commas to separate values.

Request Signing Problems


When request authentication fails, the GPI Translation API will responds to the request with a JSON error object.

This information is meant to help developers diagnose the signing issue.

Further GPI Resources on Connectors and Website Development


GPI offers custom  WCMS Translation Connectors to a variety of web content management systems in order to streamline localization workflows and access to translation project information across your enterprise. Connectors and Plugins include:



You may also find some of the following articles and links useful:


Further Information on Localization Resources

GPI frequently assists customers with multilingual website design, development and deployment, and has developed a suite of globalization tools to help you achieve your multilingual website localization project goals. You can explore them under the  Translation tools and Portals section of our website.


Please feel free to contact GPI at with any questions about our language and technology services. Also let us know if you have any interesting blog topics you would like us to cover in our future blogs. You may request a complimentary Translation Quote for your projects as well.

Content Management Systems
API, Translation API, GPI API, Translation Technology

The Rise of Ecommerce in the MENA RegionIran: Farsi Translation and Localization


Currently, there are no comments. Be the first to post one!