Some third-party APIs, such as Moz, require a signed authentication parameter in their API query to secure the identity of the user. A signed authentication parameter is comprised of one or more data elements, such as an API key or a user ID, that have been encrypted to produce a unique key. Klipfolio's Signed Authentication Builder (Hash Helper) provides a set of methods (the components added to your API query) to create this signed authentication parameter. The data elements required to build the signed authentication parameter are specified by the third-party API.

This article includes:

• Signed authentication parameter structure
• Signed Authentication Builder methods
• Append
• Encrypt
• Encode
• Print
• Expiry parameter
• Building a signed authentication parameter
• Example API queries

What is the structure of a signed authentication parameter?

The signed authentication parameter is included in the API query as a regular parameter and is built using the Signed Authentication Builder methods. The Signed Authentication Builder methods must be included in the query in the following order:

1. Append the sub-parameters required to create the signed authentication parameter.
2. Specify the encrypt method to apply to the signed authentication parameter.
3. Specify the encode method to apply to the signed authentication parameter.
4. Apply the print method to return the text representation of the signed authentication parameter.

Note: Queries built for Amazon Web Services applications follow a different procedure. Click here for an example.

Continue reading to learn more about each of the Signed Authentication Builder methods.

Signed Authentication Builder methods

Methods are the components that must be inserted into your API query to create a signed authentication parameter. Signed Authentication Builder methods can be applied iteratively, or “chained”, as needed, depending on the signed authentication requirements for a given API. For example, the Moz signed authentication parameter applies each of the append methods described below.

Append

The append methods are used to build the signed authentication parameter using the data elements specified by the third-party API.

append("data") Append a data element (in quotation marks) to the signed authentication parameter. For example,
hash.append("mozscape-a1b2c3d4e5")

append(hash.getExpiryTime(secondsFromRequest)) Append the Unix time value that is secondsFromRequest in the future from the time the method is executed. For example,
hash.append(hash.getExpiryTime(240))

appendNewLine() Append a newline character to the signed authentication parameter. For example,
hash.append("beforeNewLine").appendNewLine().append("afterNewLine")

Encrypt

Encrypt methods are used to encode your query so only your API provider can access it, protecting your information from unauthorized users. Select one or more of the encrypt methods below, based on the requirements of whichever third-party API you’re using.

encodeMd5() Convert the signed authentication parameter to a 16-byte MD5-encoded value. This is typically represented by a 32-digit hexadecimal number which can be retrieved using the toHex() method.

encodeSha1() Convert the signed authentication parameter to a 20-byte SHA1-encoded value. This is typically represented by a 40-digit hexadecimal number which can be retrieved using the toHex() method.

encodeHmacSha1 ("secretKey") Convert the signed authentication parameter to a HmacSha1-encoded value. This requires a secretKey which, if required by the API, is provided with the API credentials.

encodeHmacSha256 ("secretKey") Convert the signed authentication parameter to a HmacSha256-encoded value. This requires a secretKey which, if required by the API, is provided with the API credentials.

Encode

The following encode methods convert the signed authentication parameter to the required output format.

encodeBase64() Convert the signed authentication parameter to Base64 encoding.

encodeURL() Convert the signed authentication parameter to UTF-8 URL encoding.

toHex() Convert a 16-byte MD5 or 20-byte SHA1 signed authentication parameter to 32-digit and 40-digit hexadecimal numbers (2 digits per byte).

Print

To get the correct text value for your query, any expression beginning with hash.append() must end with the printDigest() print method, followed by a semicolon.

Expiry parameter

An expiry parameter is often required with signed authentication to provide additional security by limiting the length of time an API query is valid. The expiry parameter value is generated using the getExpiryTime() method. The following shows an example of an API query with an expiry parameter, expiryTime, set to 300 seconds from the time the query is sent. Note the method is suffixed with a semicolon and wrapped in curly braces.

https://api.sample.com/version/endpoint?parameter=value&expiryTime={hash.getExpiryTime(300);}

How to build a signed authentication parameter

The following procedure outlines how to incorporate the Signed Authentication Builder methods into a query. Each incremental step of the API query  is encoded (in yellow) below.

1. Create the API query as required. In this example, only one parameter, parameter1, (aside from the signed authentication parameter) will be passed to the ExampleOnly API.
   
   https://api.ExampleOnly.com/v1/data?parameter1=value1">https://api.ExampleOnly.com/v1/data?parameter1=value1

2. Append the data elements to be encrypted and encoded using sequences of hash.append() contained within curly braces. The signature in this example requires an expiry time as well as an Access ID (0123456789) and Key (a1b2c3d4e5f6).
   
   https://api.ExampleOnly.com/v1/data?parameter1=value1&signedAuthentication={hash.append(hash.getExpiryTime(300)).append("0123456789").append("a1b2c3d4e5f6")}

3. Apply the encode algorithms as required by the API. In this case, the ExampleOnly API requires MD5 encoding.
   
   https://api.ExampleOnly.com/v1/data?parameter1=value1&signedAuthentication={hash.append(hash.getExpiryTime(240)).append("0123456789").append("a1b2c3d4e5f6").encodeMd5().toHex()}


4. Apply the printDigest() method to obtain the text representation of the signed authentication parameter to be used in the API query.
   
   https://api.ExampleOnly.com/v1/data?parameter1=value1&signedAuthentication={hash.append(hash.getExpiryTime(240)).append("0123456789").append("a1b2c3d4e5f6").encodeMd5().toHex().printDigest();}

Example API queries with signed authentication parameters

After the Signed Authentication Builder methods have been applied, an API query with a signed authentication parameter encoded (in yellow) looks like this:

https://api.sample.com/version/endpoint?parameter=value &signedAuthentication={hash.append<Methods>("<dataElement>").<encryptMethods>.<encodeMethods>.printDigest();}

Note that the value assigned to the signed authentication parameter must end in a semi-colon and be wrapped in curly braces.

The following examples use Signed Authentication Builder methods (in yellow) to create the signed authentication parameters required by these APIs.

Moz

http://lsapi.seomoz.com/linkscape/url-metrics/moz.com%2fblog?Cols=4&AccessID=mozscape-b6838361ee&Expires={hash.getExpiryTime(240);}&signedAuthentication={hash.append("mozscape-a1b2c3d4e5").appendNewLine().append(hash.getExpiryTime(240)).encodeHmacSha1("0123456789abcdef0123456789abcdef").encodeBase64().encodeURL().printDigest();}